diff --git a/doc/tutorials/electrokinetics/electrokinetics.ipynb b/doc/tutorials/electrokinetics/electrokinetics.ipynb index c36584d803..3c34856287 100644 --- a/doc/tutorials/electrokinetics/electrokinetics.ipynb +++ b/doc/tutorials/electrokinetics/electrokinetics.ipynb @@ -4,7 +4,26 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this tutorial we're looking at the electrokinetics feature of espresso, which allows to describe the motion of potentially charged chemical species solvated in a fluid on a continuum level. The govering equations are known as the Poisson-Nernst-Planck equation, which is the combination of the electrostatic Poisson equation and the dynamics of the chemical species described by the Nernst-Planck equation. For the advection we solve the incompressible Navier-Stokes equation. The total set of equations is given by\n", + "# Electrokinetics\n", + "### Table of contents\n", + "1. [Introduction](#1.-Introduction)\n", + "2. [Advection-Diffusion in 2D](#2.-Advection-Diffusion-equation-in-2D)\n", + "3. [Electroosmotic flow](#3.-Electroosmotic-flow)\n", + "4. [Reaction in turbulent flow](#4.-Reaction-in-turbulent-flow)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 1. Introduction" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this tutorial we're looking at the electrokinetics feature of ESPResSo, which allows us to describe the motion of potentially charged chemical species solvated in a fluid on a continuum level. The govering equations for the solvent are known as the Poisson-Nernst-Planck equations, which is the combination of the electrostatic Poisson equation and the dynamics of the chemical species described by the Nernst-Planck equation. For the advection we solve the incompressible Navier-Stokes equation. The total set of equations is given by\n", "\n", "\\begin{aligned}\n", "\\partial_{t} n_{i} &= - \\vec{\\nabla} \\cdot \\vec{j}_{i} \\\\\n", @@ -21,26 +40,26 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Advection-Diffusion equation in 2D" + "# 2. Advection-Diffusion equation in 2D" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The first system that is simulated in this tutorial is the simple advection-diffusion of a drop of uncharged chemical species in a constant velocity field. To keep the computation time small, we restrict ourselves to a 2D problem, but the algorithm is also capable of solving the 3D advection-diffusion equation. Furthermore, we can also skip solving the electrostatic-poisson equation, since there are is no charged species present. This system can be described by the diffusion-equation for the density of the chemical species, which reads\n", + "The first system that is simulated in this tutorial is the simple advection-diffusion of a drop of uncharged chemical species in a constant velocity field. To keep the computation time small, we restrict ourselves to a 2D problem, but the algorithm is also capable of solving the 3D advection-diffusion equation. Furthermore, we can also skip solving the electrostatic Poisson equation, since there are is no charged species present. The equations we solve thus reduce to\n", "\n", "\\begin{equation}\n", "\\partial_{t} n = D \\Delta n - \\vec{\\nabla} \\cdot (\\vec{v} n).\n", "\\end{equation}\n", "\n", - "The fundamental solution of this partial diffential equation can easily be found in the case of a constant velocity field $\\vec{v}$ and a constant diffusion coefficient $D$. For a $d$-dimensional system, the solution of an inital droplet at the origin can be written as\n", + "The fundamental solution of this partial diffential equation can be found analytically in the case of a constant velocity field $\\vec{v}$ and a constant diffusion coefficient $D$. For a $d$-dimensional system, the solution of an initally infinitessimaly small droplet at the origin can be written as\n", "\n", "\\begin{equation}\n", "n(\\vec{x},t) = \\frac{1}{(4 \\pi D t)^{d/2}} \\exp \\left( - \\frac{(\\vec{x} - \\vec{v} t)^2}{4 D t} \\right).\n", "\\end{equation}\n", "\n", - "After importing the necessary packages, we start by defining the necessary parameters for the simulation. Since the electrokinetics algorithm can be coupled to the lattice Boltzmann solver for the hydrodynamics, we use it's velocity field to provide a constant velocity field for the advction of the chemical species." + "After importing the necessary packages, we start by defining the necessary parameters for the simulation." ] }, { @@ -106,7 +125,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The algorithm we are using is a grid based one, the same as the lattice Boltzmann algorithm. Therefore we start with defining a lattice, which will define the resolution of the grid we use to simulate our problem." + "We use a lattice Boltzmann flow field with constant velocity for advection.\n", + "Note that we have to set ``kT=0.0`` here to avoid random fluctuations in the flow velocity." ] }, { @@ -116,35 +136,20 @@ "outputs": [], "source": [ "lattice = espressomd.lb.LatticeWalberla(\n", - " n_ghost_layers=1, agrid=AGRID)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Next we setup the lattice Boltzmann fluid, which we only use to provide the constant velocity field for our advection and add it to the `system`-object to be intergrated when running the integrator. Note that the value for `kT` is set to 0, because we only want the constant velocity field." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "lb = espressomd.lb.LBFluidWalberla(\n", + " n_ghost_layers=1, agrid=AGRID)\n", + "lbf = espressomd.lb.LBFluidWalberla(\n", " lattice=lattice, density=FLUID_DENSITY, kinematic_viscosity=FLUID_VISCOSITY,\n", " tau=TAU, ext_force_density=EXT_FORCE_DENSITY, kT=0.0, seed=42)\n", - "lb[:, :, :].velocity = FLUID_VELOCITY\n", - "system.lb = lb" + "lbf[:, :, :].velocity = FLUID_VELOCITY\n", + "system.lb = lbf" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "To use the electrokinetics-algorithm in espresso, one needs to create an instance of the `EKContainer`-object and give it both a `tau` and `solver`, which are the timestep and the poisson-solver, respectively.\n", - "Since our species is uncharged, we don't need to solve the electrostatic Poisson-equation, so we can use the placeholder-class, which is called `EKNone`." + "To use the electrokinetics-algorithm in ESPResSo, one needs to create an instance of the `EKContainer`-object and pass it a time step `tau` and Poisson solver `solver`.\n", + "Since our species is uncharged, we don't need to solve the electrostatic Poisson equation, so we can use the placeholder-class, which is called `EKNone`." ] }, { @@ -161,8 +166,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Adding `EKSpecies` to this container will add them to be integrated by the integrator and optionally be used to calculate the charge-field used to solve the Poisson-equation.\n", - "We create an uncharged chemical species and add it to the container to calculate the advection-diffusion. It is initialized with a density of `0.0` and only the diffusion and the advection of the species is enabled." + "Now, we can add diffusive species to the container to integrate their dynamics." ] }, { @@ -176,27 +180,34 @@ "- Create an instance of the [`espressomd.electrokinetics.EKSpecies`]() and add it to the system with [`system.ekcontainer.add()`](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKContainer.add). \n", "\n", "# Hint:\n", - "- Use the defined values for `DIFFUSION_COEFFICIENT`, `KT` and `TAU`.\n", + "- Use the variables `DIFFUSION_COEFFICIENT`, `KT` and `TAU` defined above.\n", "- Enable both `advection` and `friction_coupling`.\n", "- Make sure to initialize the `density` with 0.0, and disable electrostatics by setting `valency` to 0.0 as well." ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { "solution2": "hidden" }, - "outputs": [], "source": [ + "```python\n", "species = espressomd.electrokinetics.EKSpecies(\n", " lattice=lattice, density=0.0, kT=KT,\n", " diffusion=DIFFUSION_COEFFICIENT, valency=0.0,\n", " advection=True, friction_coupling=True,\n", " ext_efield=[0., 0., 0.], tau=TAU)\n", - "system.ekcontainer.add(species)" + "system.ekcontainer.add(species)\n", + "```" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "markdown", "metadata": {}, @@ -233,7 +244,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "For the analytic solution we need the physical positions, which we need to calculated ourselves. This can be achieved using `np.meshgrid`. The advection is incooperated by a simple Galilei-transformation of the coordinate system." + "For comparison, we prepare the analytical solution and show the 2d-density as well as a slice through the center of the droplet." ] }, { @@ -242,7 +253,7 @@ "metadata": {}, "outputs": [], "source": [ - "def density(pos: np.ndarray, time: int, D: float):\n", + "def calc_gaussian(pos: np.ndarray, time: int, D: float):\n", " dim = pos.shape[-1]\n", " return (4 * np.pi * D * time)**(-dim / 2) * np.exp(-np.sum(np.square(pos), axis=-1) / (4 * D * time))\n", "\n", @@ -255,16 +266,7 @@ "# add the advection shift\n", "pos -= np.asarray(FLUID_VELOCITY[:2]) * TAU * RUN_TIME\n", "\n", - "analytic_density = density(pos=pos, time=RUN_TIME*TAU, D=DIFFUSION_COEFFICIENT)\n", - "# why is this necessary? dx=1, dt=1???\n", - "analytic_density /= np.sum(analytic_density)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To compare the results, we can plot the density as image-plots as well as only a diagonal slice of the density as a line-plot." + "analytic_density = calc_gaussian(pos=pos, time=RUN_TIME*TAU, D=DIFFUSION_COEFFICIENT)" ] }, { @@ -291,7 +293,7 @@ "source": [ "values_diagonal = np.diagonal(system.ekcontainer[0][:, :, 0].density)\n", "analytic_diagonal = np.diagonal(analytic_density)\n", - "positions_diagonal = np.arange(len(values_diagonal)) * np.sqrt(2)\n", + "positions_diagonal = np.arange(len(values_diagonal)) * np.sqrt(2) * AGRID\n", "\n", "fig = plt.figure(figsize=(8, 5))\n", "ax = fig.gca()\n", @@ -309,28 +311,23 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "From the plot one can see that the position of the density-peak matches well. However, one also sees a slightly larger diffusive behavior than expected. The reason is the used discretization for the advection, which introduces an artifical diffusion to the system. This is a limitation of the algorithm, which is why it cannot be applied to pure advection problems." + "From the plot one can see that the position of the density-peak matches well. However, one also sees that the droplet in the simulation has spread more than it should. The reason is that the discretization used for the advection term introduces an artifical, additional diffusion to the system. This is a fundamental limitation of the algorithm, which is why it cannot be applied to pure advection problems." ] }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Pressure-driven vs electroosmotic flow" + "# 3. Electroosmotic flow" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The next system in this tutorial is a simple slit pore, as depicted in Figure 1. It consists of an infinite plate capacitor with a electrolytic solution trapped in between. The plates of the capactior carry a constant surface charge and the counterions are solvated in the liquid. This setup will cause the ions to accumulate on the surface of the plates, forming a characteristic ion density profile, which can be solved in a mean-field manner using the Poisson-Boltzmann equation. Since the system is translational symmetric in the direction parallel to the plates, the equations for parallel and orthogonal direction will decouple. This also means that applying an external electric field in direction parallel to the plates will not change the distribution of the ions, but will result in a flow of the fluid. This characteristic flow profile is called electroomsotic flow.\n", + "The next system in this tutorial is a simple slit pore, as shown in Figure 1. It consists of an infinite plate capacitor with an electrolytic solution trapped in between the plates. The plates of the capactior carry a constant surface charge and the counterions are solvated in the liquid. \n", + "\n", + "Charge attraction will cause the ions to accumulate near the surfaces, forming a characteristic ion density profile, which can be calculated analytically using the Poisson-Boltzmann equation. Since the system has translational symmetry in the directions parallel to the plates, the equations for parallel and orthogonal direction decouple. This means that applying an external electric field in a direction parallel to the plates will not change the distribution of the ions along the orthogonal direction. It will however cause motion of the ions and consequently the fluid: The characteristic flow profile of electroosmotic flow.\n", "\n", "
\n", " missing\n", @@ -344,38 +341,42 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Due to the symmetries of the system, it effectively reduces to a 1D problem. Analytically, this system can be described by the Poisson-Boltzmann equation:\n", + "### Analytical solution\n", + "\n", + "Due to the symmetries of the system, it effectively reduces to a 1D problem along the orthogonal axis. The system can be described by the Poisson-Boltzmann equation:\n", "\n", "$$\n", "\\partial_{x}^2 \\phi(x) = \\frac{1}{\\epsilon_{0} \\epsilon_{\\mathrm{r}}} \\sum_{i} z_{i} e n_{i}(x) \\exp \\left( -\\frac{z_{i} e \\phi(x)}{k_{\\mathrm{B}} T} \\right)\n", "$$\n", "\n", - "where $x$ is the normal-direction of the plates. Since we will only simulate a single ion species, the counterions, the sum only has a single summand. The analytic solution of the potential is then given by:\n", + "where $x$ is the normal-direction of the plates. Since we will only simulate a single ion species, the counterions, the sum only has a single summand. The solution for the potential is then given by:\n", "\n", "\\begin{equation}\n", "\\phi(x) = -\\frac{k_{B}T}{z e} \\log \\left[ \\frac{C^2 \\epsilon_{0} \\epsilon_{\\mathrm{r}}}{2 k_{B}T } \\cos^{-2} \\left( \\frac{z e C}{2 k_{B} T} x \\right) \\right], \\qquad \\text{with } \\left\\| \\frac{z e C}{2 k_{B} T} \\right\\| < \\frac{\\pi}{2},\n", "\\end{equation}\n", "\n", - "where $C$ is an integration constant that is to be determined by the boundary conditions. The ion density follows then from the potential and reads\n", + "where $C$ is an integration constant that is to be determined by the boundary conditions. The ion density follows then from the potential as\n", "\n", "\\begin{equation}\n", "n(x) = \\frac{C^2 \\epsilon_{0} \\epsilon_{\\mathrm{r}}}{2 k_{B}T} \\cos^{-2} \\left( \\frac{z e C}{2 k_{B} T} x \\right).\n", "\\end{equation}\n", "\n", - "To find the integration constant we can use that the total system has to be charge neutral, i.e. the total charge on the plates is counterbalanced by the counterions. This leads to the following equation\n", + "To find the integration constant we use fact that the total system has to be charge neutral, i.e., the total charge on the plates is counterbalanced by the counterions. This leads to the following equation\n", "\n", "\\begin{equation}\n", "C \\tan \\left( \\frac{z e d}{4 k_{B} T} C \\right) = - \\frac{e^2}{\\epsilon_{0} \\epsilon_{\\mathrm{r}}} \\sigma,\n", "\\end{equation}\n", "\n", - "where $\\sigma$ is the surface charge density of the plates. This is a transcendental equation, which can be solved numerically to find $C$. The electric field in the system is then applied in the $y$-direction of the system.\n", - "Fluid flow is described by the incompressible Navier-Stokes equation, which due to the symmetries of the system reduces to a one-dimensional problem, which reads\n", + "where $\\sigma$ is the surface charge density of the plates. This is a transcendental equation, which must be solved numerically to find $C$. \n", + "\n", + "The electric field is applied in the $y$-direction, parallel to the plates.\n", + "Fluid flow is described by the incompressible Navier-Stokes equation, which due to the symmetries of the system reduces to the one-dimensional problem\n", "\n", "\\begin{equation}\n", "\\frac{\\partial^2 v_{y}(x)}{\\partial x^2} = - \\frac{\\epsilon_{0} \\epsilon_{\\mathrm{r}} z e E C^2}{2 k_{B}T \\eta} \\cos^{-2}\\left( \\frac{q C}{2 k_{B} T} x \\right).\n", "\\end{equation}\n", "\n", - "This equation can be solved analytically and the solution to it is given by\n", + "This equation can be solved analytically and the solution is given by\n", "\n", "\\begin{equation}\n", "v_{y}(x) = \\frac{2 \\epsilon_{0} \\epsilon_{\\mathrm{r}} k_{B} T E}{\\eta z e} \\log \\left( \\frac{\\cos \\left( \\frac{z e C}{2 k_{B} T} x \\right)}{\\cos \\left( \\frac{z e C}{2 k_{B} T} \\frac{d}{2} \\right)} \\right),\n", @@ -385,9 +386,16 @@ "\n", "\\begin{equation}\n", "\\sigma(x) = \\mu \\frac{\\partial v_{y}(x)}{\\partial x}\n", - "\\end{equation}\n", + "\\end{equation}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Numerical solution\n", "\n", - "This, together with the density profile, will then be compared to the analytical solution in the following." + "We start by resetting the system and defining the necessary parameters." ] }, { @@ -400,13 +408,6 @@ "system.lb = None" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "First the parameters for the simulation are specified." - ] - }, { "cell_type": "code", "execution_count": null, @@ -441,7 +442,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can now set up the electrokinetics algorithm, which follows the pattern as in the first case, starting with the LB-method." + "We can now set up the electrokinetics algorithm as in the first part of the tutorial, starting with the LB-method." ] }, { @@ -468,7 +469,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Since our species are going to carry a charge now, we need to solve the electrostatic Poisson-equation. For that, we have to specify a solver." + "Since our species are going to carry a charge now, we need to solve the full electrostatic problem. For that, we have to specify an actual solver." ] }, { @@ -479,30 +480,38 @@ }, "source": [ "# Exercise: \n", - "- Setup an Poissonsolver for the electrostatic interaction and create an instance of the [EKContainer](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKContainer) object with it and `TAU`, which is set as a member of the system-class ([`system.ekcontainer`](https://espressomd.github.io/doc/espressomd.html#espressomd.system.System.ekcontainer)).\n", + "- Set up a Poisson solver for the electrostatic interaction and use it to create an instance of the [EKContainer](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKContainer) \n", + "- Attach the container to the [`system.ekcontainer`](https://espressomd.github.io/doc/espressomd.html#espressomd.system.System.ekcontainer).\n", "\n", "# Hint:\n", "- Use an [EKFFT](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKFFT)-object as the Poisson-solver." ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { "solution2": "hidden" }, - "outputs": [], "source": [ + "```python\n", "eksolver = espressomd.electrokinetics.EKFFT(lattice=lattice, permittivity=PERMITTIVITY, single_precision=SINGLE_PRECISION)\n", "\n", - "system.ekcontainer = espressomd.electrokinetics.EKContainer(tau=TAU, solver=eksolver)" + "system.ekcontainer = espressomd.electrokinetics.EKContainer(tau=TAU, solver=eksolver)\n", + "```" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "To simulate this system, we will use two different ion species. The regular counterions, which are propagating in the system, and a species we will disable the propagation of. The latter one will be stationary and be used to describe the surface charge on the plates." + "To simulate the system, we will use two different ion species: The counterions are propagated in the fluid. The second species will be used to describe the surface charge on the plates and therefore has to be stationary (i.e. no advection, no diffusion)." ] }, { @@ -522,7 +531,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now we can distribute the ions in the domain. The counterions will be initialized with a homogeneous distribution, excluding the cells used as boundaries. The surface charge density is homogenously distributed in the boundary cells." + "Now we set the initial conditions for the ion densities. The counterions will be initialized with a homogeneous distribution, excluding the cells used as boundaries. The surface charge density is homogeneously distributed in the boundary cells." ] }, { @@ -531,7 +540,7 @@ "metadata": {}, "outputs": [], "source": [ - "density_counterions = -2.0 * SURFACE_CHARGE_DENSITY / WIDTH\n", + "density_counterions = -2.0 * SURFACE_CHARGE_DENSITY / VALENCY / WIDTH\n", "ekspecies[padding:-padding, :, :].density = density_counterions\n", "\n", "ekspecies[:padding, :, :].density = 0.0\n", @@ -545,7 +554,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Up to now we only setup the domain, but haven't specified yet which boundary-conditions we want to enforce. For that we can use `shapes` in espresso, at which we can specify boundary conditions. Since our geometry consists of two walls, we can use them to specify our boundary conditions." + "We now have to specify the boundary conditions. For this, we use ESPResSo's`shapes`." ] }, { @@ -562,21 +571,49 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "At both of them we specify No-Flux boundary conditions for the ion densities, so no fluxes will be allowed to enter or leave the wall. Furthermore, we specify a zero-density boundary condition for the species and a No-Slip boundary condition for the fluid flow." + "At both of them we specify no-flux and zero-density boundary conditions for the counterions. Furthermore, we set a no-slip boundary condition for the fluid." ] }, { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], + "cell_type": "markdown", + "metadata": { + "solution2": "hidden", + "solution2_first": true + }, "source": [ + "# Exercise\n", + "At both walls, set\n", + "\n", + "- No-flux boundary conditions for the counterions (``ekspecies``)\n", + "- Zero-density boundary conditions for the counterions\n", + "- No-slip boundary conditions for the fluid (``lbf``)\n", + "\n", + "# Hints\n", + "\n", + "- Use the shapes defined above and ``add_boundary_from_shape`` for [EK species](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKSpecies.add_boundary_from_shape) and [LB fluids](https://espressomd.github.io/doc/espressomd.html#espressomd.lb.LBFluidWalberla.add_boundary_from_shape)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "solution2": "hidden" + }, + "source": [ + "```python\n", "for shape_obj in (wall_left, wall_right):\n", " ekspecies.add_boundary_from_shape(shape=shape_obj, value=[0., 0., 0.], boundary_type=espressomd.electrokinetics.FluxBoundary)\n", " ekspecies.add_boundary_from_shape(shape=shape_obj, value=0.0, boundary_type=espressomd.electrokinetics.DensityBoundary)\n", - " lbf.add_boundary_from_shape(shape=shape_obj, velocity=[0., 0., 0.])" + " lbf.add_boundary_from_shape(shape=shape_obj, velocity=[0., 0., 0.])\n", + "```" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "markdown", "metadata": {}, @@ -615,7 +652,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "For the comparison, we have to calculate the anlytic solution" + "For comparison, we calculate the analytic solution" ] }, { @@ -700,7 +737,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "To compare this result to a pressure-driven flow, we need to turn off the external electric field and enable a constant external force density on the fluid." + "### Comparison to pressure driven flow\n", + "We can compare electroosmotic flow to pressure-driven flow. For this, we turn off the external electric field and enable a constant external force density on the fluid." ] }, { @@ -715,13 +753,6 @@ "lbf.ext_force_density = EXT_FORCE_DENSITY" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This new system can be integrated again and the exact same measurement as the one before are taken." - ] - }, { "cell_type": "code", "execution_count": null, @@ -749,7 +780,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Again we can compare our solution to an anlytic solution, which is known as the Poiseuille flow between infinite parallel plates." + "The anlaytic solution for pressure driven flow between two infinite parallel plates is known as the Poiseuille flow." ] }, { @@ -816,7 +847,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "As one can again see, the body force on the fluid did non alter the ion-density profile, and one can observe a good match for the parabolic fluid velocity." + "As one can again see, the body force on the fluid did non alter the ion-density profile.\n", + "However, because the force now applies homogeneously on the whole fluid, the flow profile looks parabolic." ] }, { @@ -869,24 +901,28 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Looking at the fluid velocity plot, one can see that the electroosmotic flow profile flattens significantly faster towards the center of the channel when compared to the pressure driven flow. The reason for this is the accumulation of the counterion-density towards the plates of the system, where the driving electric field causes the highest force on the fluid, which decays towards the center of the channel. In contrast, the Poiseuille-flow is driven by a constant, uniform driving force." + "Looking at the fluid velocity plot, one can see that the electroosmotic flow profile flattens significantly faster towards the center of the channel when compared to the pressure driven flow. The reason for this is the accumulation of the counterion-density towards the oppositely charged plates. Here, the driving electric field causes the highest force on the fluid, which decays towards the center of the channel. In contrast, the Poiseuille-flow is driven by a constant, uniform driving force." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "# Kármán vortex street with a reactive species" + "# 4. Reaction in turbulent flow" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "As a showcase for the algorithm, we are now simulating a [Kármán vortex street](https://en.wikipedia.org/wiki/K%C3%A1rm%C3%A1n_vortex_street).\n", - "Our setup consists of rigid cylinders in a fast, unsteady fluid flow, which develops to a repeating pattern of swirling vorticies behind the obstacle.\n", - "To showcase the reaction feature of the electrokinetics algorithm in espresso, we're adding several species to the system undergoing advection-diffusion, which is dominated by the downstream fluid flow in the channel.\n", - "The reaction will be included as a bulk-reaction, which means that the reaction can happen anywhere, the only requirement is that both species are present in the same lattice-cell. When this occurs, parts of these species will undergo the reaction and will turn into the product. How much of the species will transform within each timestep is determined by the respective reaction rate and the overall structure of the reaction.\n" + "To showcase the reaction feature of our electrokinetics algorithm, we simulate a simple reaction in complex flow.\n", + "For this, we choose a geometry of rigid cylinders.\n", + "At large flow velocities, a [Kármán vortex street](https://en.wikipedia.org/wiki/K%C3%A1rm%C3%A1n_vortex_street), i.e., a repeating pattern of swirling vorticies behind the obstacle, develops.\n", + " \n", + "To this flow, we will add several species undergoing advection-diffusion, which is dominated by the downstream fluid flow in the channel.\n", + "The reaction will be included as a bulk-reaction, which means that the reaction can happen anywhere, the only requirement is that both species are present in the same lattice cell. When the reaction occurs, parts of the reactant species will turn into the product. How much of the species will transform within each timestep is determined by the respective reaction rate and the overall structure of the reaction.\n", + "\n", + "We start again by resetting the system and defining parameters." ] }, { @@ -899,13 +935,6 @@ "system.lb = None" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The system is again setup in the same manner as in the previous problem, defining the dimensions of the system as well as the `time_step`." - ] - }, { "cell_type": "code", "execution_count": null, @@ -930,13 +959,6 @@ "system.box_l = BOX_L" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Since we're again using the LB/EK algorithm, we have to specify the grid, on which we want to solve our problem. For simplicity and for the sake of computation time, we restrict ourselves to a effectively 2D grid." - ] - }, { "cell_type": "code", "execution_count": null, @@ -946,10 +968,10 @@ "lattice = espressomd.lb.LatticeWalberla(\n", " n_ghost_layers=1, agrid=AGRID)\n", "\n", - "lb = espressomd.lb.LBFluidWalberla(\n", + "lbf = espressomd.lb.LBFluidWalberla(\n", " lattice=lattice, density=DENSITY_FLUID, kinematic_viscosity=VISCOSITY_KINEMATIC,\n", " tau=TAU, ext_force_density=EXT_FORCE_DENSITY, kT=KT, seed=42)\n", - "system.lb = lb\n", + "system.lb = lbf\n", "\n", "\n", "eksolver = espressomd.electrokinetics.EKNone(lattice=lattice)\n", @@ -960,11 +982,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now we can actually focus on the reactions, we want to include into our simulation. In this tutorial we choose the simple case of $A + B \\rightarrow C$, which means that equal parts of the educt species $A$ and $B$ can turn into the product species $C$.\n", - "Espresso distinguishes between educts and products by the sign of the stoechiometric coefficients, where educts have negative coefficients and products positive coefficients. Intuitively this can be understood that when a reaction happens, the density of the educts will decrease, hence the stoechiometric coefficient is negative. The reaction rate constant $r$ is the rate at which the reaction happens which usually is temperature-dependent and the order $O_i$ for a species $i$ specifies to which order the reaction depends on the density of that species. Positive orders mean that the reaction is faster the more density of this species is present, for negative orders the reaction slows down with higher density.\n", + "Now we can focus on the reactions. In this tutorial we choose the simple case of $A + B \\rightarrow C$, which means that equal parts of the educt species $A$ and $B$ can turn into the product species $C$.\n", + "ESPResSo distinguishes between educts and products by the sign of their respective stoechiometric coefficients, where educts have negative coefficients and products positive coefficients. Intuitively this can be understood that when a reaction happens, the density of the educts will decrease, hence the stoechiometric coefficient is negative. \n", + "\n", + "The reaction rate constant $r$ is the rate at which the reaction happens. The order $O_i$ for a species $i$ specifies to which order the reaction depends on the density of that species. Positive orders mean that the reaction is faster the more density of this species is present, for negative orders the reaction slows down with higher density.\n", "In general, this process can be written as $\\Gamma = r \\left[ A \\right]^{O_A} \\left[ B \\right]^{O_B} \\left[ C \\right]^{O_C}$, where $\\Gamma$ is known as the reaction rate. This is sometimes also called the [rate equation](https://en.wikipedia.org/wiki/Rate_equation).\n", "\n", - "For our specific simulation this means that all stoechiometric coefficients are $-1$ for the educts and $1$ for the product. The order of the educts is $1$ and the order of the product is $0$. This means that the more amount of both educts is present, the more will react and the amount of product present won't influence the amount of product that will be produced." + "For our specific simulation this means that all stoechiometric coefficients are $-1$ for the educts and $1$ for the product. We choose the order of the educts as $1$ and the order of the product as $0$. This means that the more amount of both educts is present, the more will react and the amount of product present won't have an influence." ] }, { @@ -975,16 +999,16 @@ "source": [ "REACTION_RATE_CONSTANT = 0.1\n", "\n", - "EDUCT_COEFFS = [1.0, 1.0]\n", - "PRODUCT_COEFFS = [1]" + "EDUCT_COEFFS = [-1, -1]\n", + "EDUCT_ORDERS = [1,1]\n", + "PRODUCT_COEFFS = [1]\n", + "PRODUCT_ORDERS = [0]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Now that we specified all coefficients for the reaction, we can setup all the necessary objects for the simulations.\n", - "\n", "We create each involved species and directly specify their boundary-conditions for the domain-boundaries. We set the initial density of the species to 0 and also add Dirichlet boundary conditions of zero density at both the inlet and the outlet of the system." ] }, @@ -997,7 +1021,7 @@ "educt_species = []\n", "product_species = []\n", "reactants = []\n", - "for coeff in EDUCT_COEFFS:\n", + "for coeff, order in zip(EDUCT_COEFFS, EDUCT_ORDERS):\n", " species = espressomd.electrokinetics.EKSpecies(\n", " lattice=lattice, density=0.0, kT=KT,\n", " diffusion=DIFFUSION_COEFFICIENT, valency=0.0,\n", @@ -1007,13 +1031,13 @@ " reactants.append(\n", " espressomd.electrokinetics.EKReactant(\n", " ekspecies=species,\n", - " stoech_coeff=-coeff,\n", - " order=coeff))\n", + " stoech_coeff=coeff,\n", + " order=order))\n", " educt_species.append(species)\n", " species[0,:,:].density_boundary = espressomd.electrokinetics.DensityBoundary(0.0)\n", " species[-1,:,:].density_boundary = espressomd.electrokinetics.DensityBoundary(0.0)\n", "\n", - "for coeff in PRODUCT_COEFFS:\n", + "for coeff, order in zip(PRODUCT_COEFFS, PRODUCT_ORDERS):\n", " species = espressomd.electrokinetics.EKSpecies(\n", " lattice=lattice, density=0.0, diffusion=DIFFUSION_COEFFICIENT,\n", " kT=KT, valency=0.0, advection=True, friction_coupling=True,\n", @@ -1023,7 +1047,7 @@ " espressomd.electrokinetics.EKReactant(\n", " ekspecies=species,\n", " stoech_coeff=coeff,\n", - " order=0.0))\n", + " order=order))\n", " product_species.append(species)\n", " species[0,:,:].density_boundary = espressomd.electrokinetics.DensityBoundary(0.0)\n", " species[-1,:,:].density_boundary = espressomd.electrokinetics.DensityBoundary(0.0)" @@ -1032,34 +1056,41 @@ { "cell_type": "markdown", "metadata": { - "solution2": "shown", + "solution2": "hidden", "solution2_first": true }, "source": [ "# Exercise:\n", - "- Create an instance of [`EKBulkReaction`](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKBulkReaction) using the previously setup `reactants` and activate the reaction by adding it to [`system.ekcontainer.reactions`](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKContainer.reactions).\n" + "- Create an instance of [`EKBulkReaction`](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKBulkReaction) using the previously created `reactants` and activate the reaction by adding it to [`system.ekcontainer.reactions`](https://espressomd.github.io/doc/espressomd.html#espressomd.electrokinetics.EKContainer.reactions).\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "metadata": { - "solution2": "shown" + "solution2": "hidden" }, - "outputs": [], "source": [ + "```python\n", "reaction = espressomd.electrokinetics.EKBulkReaction(\n", " reactants=reactants, coefficient=REACTION_RATE_CONSTANT, lattice=lattice, tau=TAU)\n", "\n", - "system.ekcontainer.reactions.add(reaction)" + "system.ekcontainer.reactions.add(reaction)\n", + "```" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The next thing to add to the system is the cylindrical boundaries, which act as the boundaries for the Kármán vorticies to form. These are placed close to the inlet of the system and also act as impenetrable boundaries for the species.\n", - "Since espresso uses periodic-boundary conditions, we need to add a total of three cylinders to the system, which will form two complete cylinders in the periodic system." + "The next thing to add to the system is the cylindrical obstacles, which act as the boundaries for the Kármán vorticies to form. These are placed close to the inlet of the system and also act as impenetrable boundaries for the species.\n", + "Since ESPResSo uses periodic-boundary conditions, we need to add a total of three cylinders to the system, which will form two complete cylinders in the periodic system." ] }, { @@ -1084,7 +1115,7 @@ " ))\n", "\n", "for shape in shape_cylinder:\n", - " lb.add_boundary_from_shape(shape)\n", + " lbf.add_boundary_from_shape(shape)\n", " for spec in (*educt_species, *product_species):\n", " spec.add_boundary_from_shape(shape, value=[0,0,0], boundary_type=espressomd.electrokinetics.FluxBoundary)\n", " spec.add_boundary_from_shape(shape, value=0., boundary_type=espressomd.electrokinetics.DensityBoundary)" @@ -1095,7 +1126,7 @@ "metadata": {}, "source": [ "Up to this point there is no species present anywhere in the system and also no way for it to enter the system. Since the reaction is irreversible in our setup, we need to introduce some density of both the educt species to the system.\n", - "For that we setup two additional Dirichlet boundary conditions in the domain, where we fix the species density to a constant, non-zero value. This is done in such a way, that these two sources are spatially separated and only upon diffusion of the species through the channel, they will be able to react with each other. " + "For that we set two additional Dirichlet boundary conditions (sources) in the domain, where we fix the species' density to a constant, non-zero value. The sources are placed some distance apart such that the reaction happens further downstream when diffusion mixes the two species." ] }, { @@ -1157,7 +1188,7 @@ "box_width = lattice.shape[1]\n", "box_height = lattice.shape[0]\n", "\n", - "boundary_mask = lb[:, :, 0].boundary != None\n", + "boundary_mask = lbf[:, :, 0].boundary != None\n", "\n", "progress_bar = tqdm.tqdm(total=TOTAL_FRAMES)\n", "\n", @@ -1192,13 +1223,13 @@ "ys = np.arange(box_height)\n", "X, Y = np.meshgrid(xs, ys)\n", "\n", - "flowfield = lb[:, :, 0].velocity\n", + "flowfield = lbf[:, :, 0].velocity\n", "quiver = ax4.quiver(X, Y, flowfield[..., 1], flowfield[..., 0], scale=100)\n", "\n", "def draw_frame(frame):\n", " system.integrator.run(100)\n", " \n", - " flowfield = np.copy(lb[:, :, 0].velocity)\n", + " flowfield = np.copy(lbf[:, :, 0].velocity)\n", " e1 = np.copy(educt_species[0][:, :, 0].density)\n", " e2 = np.copy(educt_species[1][:, :, 0].density)\n", " p = np.copy(product_species[0][:, :, 0].density)\n", @@ -1225,20 +1256,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Looking at the movie of the species densities one can see that the fluid flow is advecting the educt species from their source locations past the cylinders into the system, which is when they start to mix and react, such that the product will form. The density of the product is then increasing towards the outflow-location of the channel, at which it will then be deleted because of our zero-density boundary condition." + "Looking at the movie of the species densities one can see that the fluid flow advects the educt species from their source locations past the cylinders into the system. Here, they start to mix and react, such that the product forms.\n", + "The vortex street behind the obstacles enhances mixing through fluid turbulence. The density of the product then increases towards the outflow-location of the channel, where it is deleted because of our zero-density boundary condition." ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" },