From efacee2da2bc083b56911d3e310fd45b69cc5398 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 23 Aug 2024 19:48:16 +0200 Subject: [PATCH] Edit and format tutorials --- doc/tutorials/constant_pH/constant_pH.ipynb | 4 +- .../electrodes/electrodes_part2.ipynb | 7 +- .../ferrofluid/ferrofluid_part1.ipynb | 74 +++++++++---------- .../ferrofluid/ferrofluid_part2.ipynb | 22 +++--- .../ferrofluid/ferrofluid_part3.ipynb | 8 +- .../langevin_dynamics/langevin_dynamics.ipynb | 2 +- .../widom_insertion/widom_insertion.ipynb | 12 ++- 7 files changed, 69 insertions(+), 60 deletions(-) diff --git a/doc/tutorials/constant_pH/constant_pH.ipynb b/doc/tutorials/constant_pH/constant_pH.ipynb index 8dabb3dc2b..0c52dde352 100644 --- a/doc/tutorials/constant_pH/constant_pH.ipynb +++ b/doc/tutorials/constant_pH/constant_pH.ipynb @@ -745,7 +745,7 @@ "id": "cd417295-bab3-46a5-a574-fc60d06371a5", "metadata": {}, "source": [ - "We will initialize the zndraw visualizer to visualize the simulation for increasing pH value:" + "We will initialize ZnDraw to visualize the simulation for increasing pH values:" ] }, { @@ -753,7 +753,7 @@ "execution_count": null, "id": "04dd303c", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ diff --git a/doc/tutorials/electrodes/electrodes_part2.ipynb b/doc/tutorials/electrodes/electrodes_part2.ipynb index 1aaf34d86e..e7007c62e3 100644 --- a/doc/tutorials/electrodes/electrodes_part2.ipynb +++ b/doc/tutorials/electrodes/electrodes_part2.ipynb @@ -1010,7 +1010,7 @@ "With the above knowledge, we can now assess the \n", "differential capacitance of the system, by changing the applied voltage\n", "difference and determining the corresponding surface charge density.\n", - "We will use the ZnDraw visualizer to visualize our system:" + "We will use ZnDraw to visualize our system:" ] }, { @@ -1033,8 +1033,9 @@ "vis = espressomd.zn.Visualizer(system, colors=color, radii=radii)\n", "#vis.draw_constraints([floor, ceiling])\n", "\n", - "#note: The system displayed is the enlarged system as you can see the ELG-GAP along the nonperiodic direction. The particles are only in the smaller subsystem.\n", - "#note: The particles are shown bigger for visualization purpose." + "# note: you may need to zoom out since the ELC gap region takes a significant portion of\n", + "# the box along the non-periodic direction. The particles are only in the smaller subsystem.\n", + "# note: The particles are shown bigger for visualization purpose." ] }, { diff --git a/doc/tutorials/ferrofluid/ferrofluid_part1.ipynb b/doc/tutorials/ferrofluid/ferrofluid_part1.ipynb index 2bd4d2ad56..72d116a517 100644 --- a/doc/tutorials/ferrofluid/ferrofluid_part1.ipynb +++ b/doc/tutorials/ferrofluid/ferrofluid_part1.ipynb @@ -15,15 +15,13 @@ "source": [ "## Table of Contents\n", "1. [Introduction](#Introduction)\n", - "2. [The Model](#The-Model)\n", + "2. [The model](#The-model)\n", "3. [Structure of this tutorial](#Structure-of-this-tutorial)\n", - "4. [Compiling ESPResSo for this Tutorial](#Compiling-ESPResSo-for-this-Tutorial)\n", - "5. [A Monolayer-Ferrofluid System in ESPResSo](#A-Monolayer-Ferrofluid-System-in-ESPResSo)\n", + "4. [Compiling ESPResSo for this tutorial](#Compiling-ESPResSo-for-this-tutorial)\n", + "5. [A monolayer-ferrofluid system in ESPResSo](#A-monolayer-ferrofluid-system-in-ESPResSo)\n", " 1. [Setup](#Setup)\n", - " 2. [Sampling](#Sampling)\n", - " 3. [Sampling with animation](#Sampling-with-animation)\n", - " 4. [Sampling without animation](#Sampling-without-animation)\n", - " 5. [Cluster distribution](#Cluster-distribution)" + " 2. [Sampling and cluster analysis](#Sampling-and-cluster-analysis)\n", + " 3. [Cluster distribution](#Cluster-distribution)" ] }, { @@ -54,10 +52,8 @@ "metadata": {}, "source": [ "
\n", - "\n", - "
\n", - "
Figure 1: Schematic representation of electrostatically stabilization (picture top) and steric stabilization (picture bottom) [3]
\n", - "
\n", + "\n", + "
Figure 1: Schematic representation of electrostatically stabilization (picture top) and steric stabilization (picture bottom) [3]
\n", "
" ] }, @@ -67,10 +63,8 @@ "metadata": {}, "source": [ "
\n", - "ferrofluid on glass plate under which a strong magnet is placed\n", - "
\n", - "
Figure 2: Real Ferrofluid exposed to an external magnetic field (neodymium magnet) [4]
\n", - "
\n", + "ferrofluid on glass plate under which a strong magnet is placed\n", + "
Figure 2: Real ferrofluid exposed to an external magnetic field (neodymium magnet) [4]
\n", "
" ] }, @@ -79,7 +73,7 @@ "id": "095339c1", "metadata": {}, "source": [ - "## The Model" + "## The model" ] }, { @@ -124,7 +118,7 @@ " \\lambda = \\frac{\\tilde{u}_{\\text{DD}}}{u_T} = \\gamma \\frac{\\mu^2}{k_{\\text{B}}T\\sigma^3}\n", "\\end{equation}\n", "\n", - "where $u_\\mathrm{T} = k_{\\text{B}}T$ is the thermal energy and $\\tilde{u}_{DD}$ is the absolute value of the dipole-dipole interaction energy at close contact (cc) and head-to-tail configuration (htt) (see figure 4) per particle, i.e. in formulas it reads\n", + "where $u_\\mathrm{T} = k_{\\text{B}}T$ is the thermal energy and $\\tilde{u}_{DD}$ is the absolute value of the dipole-dipole interaction energy at close contact (cc) and head-to-tail configuration (htt) (see figure 3) per particle, i.e. in formulas it reads\n", "\n", "\\begin{equation}\n", " \\tilde{u}_{\\text{DD}} = \\frac{ \\left| u_{\\text{DD}}^{\\text{htt, cc}} \\right| }{2}\n", @@ -143,11 +137,9 @@ "id": "62b95d9c", "metadata": {}, "source": [ - "
\n", - "schematic representation of head to tail configuration\n", - "
\n", - "
Figure 4: Schematic representation of the head-to-tail configuration of two magnetic particles at close contact.
\n", - "
\n", + "
\n", + "schematic representation of head to tail configuration\n", + "
Figure 3: Schematic representation of the head-to-tail configuration of two magnetic particles at close contact.
\n", "
" ] }, @@ -182,7 +174,7 @@ "id": "b6d5a65e", "metadata": {}, "source": [ - "## Compiling ESPResSo for this Tutorial" + "## Compiling ESPResSo for this tutorial" ] }, { @@ -218,7 +210,7 @@ "id": "a0bffbeb", "metadata": {}, "source": [ - "## A Monolayer-Ferrofluid System in ESPResSo" + "## A monolayer-ferrofluid system in ESPResSo" ] }, { @@ -324,7 +316,8 @@ "id": "136aa645", "metadata": {}, "source": [ - "## Exercise:\n", + "**Exercise:**\n", + "\n", "How large does `BOX_SIZE` have to be for a system of `N_PART` particles with a volume (area) fraction `PHI`?\n", "Define `BOX_SIZE`." ] @@ -384,7 +377,8 @@ "outputs": [], "source": [ "# Lennard-Jones interaction\n", - "system.non_bonded_inter[0, 0].lennard_jones.set_params(epsilon=LJ_EPSILON, sigma=LJ_SIGMA, cutoff=LJ_CUT, shift=\"auto\")" + "system.non_bonded_inter[0, 0].lennard_jones.set_params(\n", + " epsilon=LJ_EPSILON, sigma=LJ_SIGMA, cutoff=LJ_CUT, shift=\"auto\")" ] }, { @@ -394,7 +388,7 @@ "source": [ "Now we generate random positions and orientations of the particles and their dipole moments. \n", "\n", - "**Hint:**\n", + "Hint:\n", "It should be noted that we seed the random number generator of numpy. Thus the initial configuration of our system is the same every time this script will be executed. You can change it to another one to simulate with a different initial configuration." ] }, @@ -403,9 +397,11 @@ "id": "c49729f7", "metadata": {}, "source": [ - "## Exercise:\n", + "**Exercise:**\n", + "\n", "How does one set up randomly oriented dipole moments?\n", - "*Hint*: Think of the way that different methods could introduce a bias in the distribution of the orientations.\n", + "\n", + "Hint: Think of the way that different methods could introduce a bias in the distribution of the orientations.\n", "\n", "Create a variable `dip` as a `N_PART x 3` numpy array, which contains the randomly distributed dipole moments." ] @@ -523,7 +519,7 @@ "For the simulation of our system we choose the velocity Verlet integrator.\n", "After that we set up the thermostat which is, in our case, a Langevin thermostat to simulate in an NVT ensemble.\n", "\n", - "**Hint:**\n", + "Hint:\n", "It should be noted that we seed the Langevin thermostat, thus the time evolution of the system is partly predefined.\n", "Partly because of the numeric accuracy and the automatic tuning algorithms of Dipolar P3M and DLC where the resulting parameters are slightly different every time.\n", "You can change the seed to get a guaranteed different time evolution." @@ -562,7 +558,7 @@ "execution_count": null, "id": "fd12b1f6", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ @@ -592,7 +588,7 @@ "execution_count": null, "id": "95c4a8b6", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ @@ -608,7 +604,7 @@ "id": "a6c4c46b", "metadata": {}, "source": [ - "## Sampling and cluster analysis" + "### Sampling and cluster analysis" ] }, { @@ -617,7 +613,7 @@ "metadata": {}, "source": [ "To quantify the number of clusters and their respective sizes, we now want to perform a cluster analysis.\n", - "For that we can use ESPREsSo's [cluster analysis class](https://espressomd.github.io/doc/analysis.html?highlight=cluster%20analysis#cluster-analysis).\n", + "For that we can use ESPResSo's [cluster analysis class](https://espressomd.github.io/doc/analysis.html#cluster-analysis).\n", "The system will be sampled over 100 loops." ] }, @@ -636,7 +632,7 @@ "id": "2f6d201a", "metadata": {}, "source": [ - "## Exercise:\n", + "**Exercise:**\n", "\n", "Setup a cluster analysis object (`ClusterStructure` class) and assign its instance to the variable `cluster_structure`.\n", "As criterion for the cluster analysis use a distance criterion where particles are assumed to be\n", @@ -717,7 +713,7 @@ "id": "98b99dd6", "metadata": {}, "source": [ - "## Exercise:\n", + "**Exercise:**\n", "\n", "Write an integration loop which runs a cluster analysis on the system, saving the number of clusters `n_clusters` and the size distribution `cluster_sizes`.\n", "Take the following as a starting point:\n", @@ -803,7 +799,7 @@ "id": "4c0828ea", "metadata": {}, "source": [ - "## Cluster distribution" + "### Cluster distribution" ] }, { @@ -819,12 +815,12 @@ "id": "1c6be57c", "metadata": {}, "source": [ - "## Exercise:\n", + "**Exercise:**\n", "\n", "Use `numpy` to calculate a histogram of the cluster sizes and assign it to the variable `size_dist`.\n", "Take only clusters up to a size of 19 particles into account.\n", "\n", - "*Hint*: In order not to count clusters with size 20 or more, one may include an additional bin containing these.\n", + "Hint: In order not to count clusters with size 20 or more, one may include an additional bin containing these.\n", "The reason for that is that `numpy` defines the histogram bins as half-open intervals with the open border at the upper bin edge.\n", "Consequently clusters of larger sizes are attributed to the last bin.\n", "By not using the last bin in the plot below, these clusters can effectively be neglected." diff --git a/doc/tutorials/ferrofluid/ferrofluid_part2.ipynb b/doc/tutorials/ferrofluid/ferrofluid_part2.ipynb index e13eb759f9..80dcc881bb 100644 --- a/doc/tutorials/ferrofluid/ferrofluid_part2.ipynb +++ b/doc/tutorials/ferrofluid/ferrofluid_part2.ipynb @@ -167,7 +167,8 @@ "pos = box_size * np.hstack((np.random.random((N_PART, 2)), np.zeros((N_PART, 1))))\n", "\n", "# Add particles\n", - "particles = system.part.add(pos=pos, rotation=N_PART * [(True, True, True)], dip=dip, fix=N_PART * [(False, False, True)])\n", + "particles = system.part.add(pos=pos, rotation=N_PART * [(True, True, True)],\n", + " dip=dip, fix=N_PART * [(False, False, True)])\n", "\n", "# Remove overlap between particles by means of the steepest descent method\n", "MASS = 1.0\n", @@ -270,7 +271,7 @@ "execution_count": null, "id": "7750295c", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ @@ -471,7 +472,8 @@ "pos = box_size * np.hstack((np.random.random((N_PART, 2)), np.zeros((N_PART, 1))))\n", "\n", "# Add particles\n", - "particles = system.part.add(pos=pos, rotation=N_PART * [(True, True, True)], dip=dip, fix=N_PART * [(False, False, True)])\n", + "particles = system.part.add(pos=pos, rotation=N_PART * [(True, True, True)],\n", + " dip=dip, fix=N_PART * [(False, False, True)])\n", "\n", "# Remove overlap between particles by means of the steepest descent method\n", "system.integrator.set_steepest_descent(f_max=0, gamma=0.1, max_displacement=0.05)\n", @@ -803,7 +805,7 @@ "outputs": [], "source": [ "def dL_dB(alpha):\n", - " return (1. / (alpha**2.) - 1. / ((np.sinh(alpha))**2.)) * dipm / (KT)" + " return (1. / (alpha**2) - 1. / np.sinh(alpha)**2) * dipm / (KT)" ] }, { @@ -884,8 +886,8 @@ "plt.xlabel(r'$\\alpha$', fontsize=20)\n", "plt.ylabel(r'$M^*$', fontsize=20)\n", "plt.plot(x, L(x), label='Langevin function')\n", - "plt.plot(x, magnetization_approx_perp(x), label='q2D approximation $\\perp$')\n", - "plt.plot(x, magnetization_approx_para(x), label='q2D approximation $\\parallel$')\n", + "plt.plot(x, magnetization_approx_perp(x), label=r'q2D approximation $\\perp$')\n", + "plt.plot(x, magnetization_approx_para(x), label=r'q2D approximation $\\parallel$')\n", "# < exercise >\n", "plt.legend(fontsize=20)\n", "plt.show()\n", @@ -907,10 +909,10 @@ "plt.xlabel(r'$\\alpha$', fontsize=20)\n", "plt.ylabel(r'$M^*$', fontsize=20)\n", "plt.plot(x, L(x), label='Langevin function')\n", - "plt.plot(x, magnetization_approx_perp(x), label='q2D approximation $\\perp$')\n", - "plt.plot(x, magnetization_approx_para(x), label='q2D approximation $\\parallel$')\n", - "plt.plot(alphas, magnetization_perp / N_PART, 'o', label='simulation results $\\perp$')\n", - "plt.plot(alphas, magnetization_para / N_PART, 'o', label='simulation results $\\parallel$')\n", + "plt.plot(x, magnetization_approx_perp(x), label=r'q2D approximation $\\perp$')\n", + "plt.plot(x, magnetization_approx_para(x), label=r'q2D approximation $\\parallel$')\n", + "plt.plot(alphas, magnetization_perp / N_PART, 'o', label=r'simulation results $\\perp$')\n", + "plt.plot(alphas, magnetization_para / N_PART, 'o', label=r'simulation results $\\parallel$')\n", "plt.legend(fontsize=20)\n", "plt.show()" ] diff --git a/doc/tutorials/ferrofluid/ferrofluid_part3.ipynb b/doc/tutorials/ferrofluid/ferrofluid_part3.ipynb index 8bce1733db..b3be7c3c32 100644 --- a/doc/tutorials/ferrofluid/ferrofluid_part3.ipynb +++ b/doc/tutorials/ferrofluid/ferrofluid_part3.ipynb @@ -273,7 +273,7 @@ "execution_count": null, "id": "89966f9b", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ @@ -334,11 +334,11 @@ "execution_count": null, "id": "bd24f8eb", "metadata": { - "scrolled": true + "scrolled": false }, "outputs": [], "source": [ - "# initialize array for hold the sampled dipole moments\n", + "# initialize array that will hold the sampled dipole moments\n", "dipms = np.full((loops, 3), np.nan)\n", "\n", "# sample dipole moment\n", @@ -542,7 +542,7 @@ "id": "395a4fc0-baaf-48d6-8b88-b8ba42408bfe", "metadata": {}, "source": [ - "Additionally, we will visualize the sampling of the magnetization curve using the ZnDraw visualizer. Note, that the magnetic field is increasing during the video." + "Additionally, we will visualize the sampling of the magnetization curve using ZnDraw. Note, that the magnetic field is increasing during the video." ] }, { diff --git a/doc/tutorials/langevin_dynamics/langevin_dynamics.ipynb b/doc/tutorials/langevin_dynamics/langevin_dynamics.ipynb index 5f6471c40b..6c602341e1 100644 --- a/doc/tutorials/langevin_dynamics/langevin_dynamics.ipynb +++ b/doc/tutorials/langevin_dynamics/langevin_dynamics.ipynb @@ -240,7 +240,7 @@ "id": "933cea77-4bca-47a6-8a82-cc13d07ec673", "metadata": {}, "source": [ - "Now we can do the actual simulation where we simulate for different friction coefficients and sample our observables:" + "Now we can do the actual production run where we simulate for different friction coefficients and sample our observables:" ] }, { diff --git a/doc/tutorials/widom_insertion/widom_insertion.ipynb b/doc/tutorials/widom_insertion/widom_insertion.ipynb index 04e9140afd..cf06a7c507 100644 --- a/doc/tutorials/widom_insertion/widom_insertion.ipynb +++ b/doc/tutorials/widom_insertion/widom_insertion.ipynb @@ -195,6 +195,7 @@ "Now we are ready to set up the system. Because we will need to rescale the simulation box, we will initially only set up the short-range interactions.\n", "\n", "**Exercise:**\n", + "\n", "* Set up a system with box length $10\\,\\sigma$, integrator time step $\\Delta t=0.01 \\,\\tau$ ($\\tau$ is the Lennard-Jones timescale, i.e. equal to 1 in the employed unit system) and Verlet skin width of $\\delta = 0.4\\sigma$\n", "* Add a total of ``N_ION_PAIRS`` ion pairs at random positions to the simulation box\n", "* Add a WCA interaction (purely repulsive Lennard-Jones interaction) between the particles\n", @@ -244,10 +245,12 @@ "metadata": {}, "source": [ "**Exercise:**\n", + "\n", "* Implement a function ``system_setup(c_salt_SI)`` that takes the desired salt concentration ``c_salt_SI`` in SI-units (mol/l) as an argument and rescales the simulation box accordingly\n", "* Afterwards, the function should also add the P3M actor to account for electrostatic interactions\n", "\n", "**Hints:**\n", + "\n", "* Use the prefactor ``PREF`` defined above to convert the concentration from SI-units to the unit system employed in the simulation\n", "* An accuracy of $10^{-3}$ for the P$^3$M should be enough for this exercise" ] @@ -290,9 +293,11 @@ "metadata": {}, "source": [ "**Exercise:**\n", + "\n", "* Implement a function ``warmup()`` that removes potential overlaps between particles with 10000 steps of the steepest descent integrator and performs a warmup integration with 100 loops of 100 simulation steps\n", "\n", "**Hints:**\n", + "\n", "* keep in mind that after the overlaps have been removed, the integrator should be switched\n", " back to Velocity-Verlet with the Langevin thermostat (using ``GAMMA`` and ``KT``)\n", " in order to perform a warmup integration\n", @@ -340,10 +345,11 @@ "metadata": {}, "source": [ "**Exercise:**\n", - "* Add the functionality to perform Widom insertion moves. Make sure that you always insert an ion pair in order to conserve the system electroneutrality.\n", "\n", + "* Add the functionality to perform Widom insertion moves. Make sure that you always insert an ion pair in order to conserve the system electroneutrality.\n", "\n", "**Hints:**\n", + "\n", "* Refer to the documentation to find out how to set up Widom particle insertion ([Widom Insertion](https://espressomd.github.io/doc/reaction_methods.html#widom-insertion-for-homogeneous-systems))" ] }, @@ -377,6 +383,7 @@ "metadata": {}, "source": [ "**Exercise:**\n", + "\n", "* Implement a function ``calculate_excess_chemical_potential(n_md_steps, n_mc_steps, sample_size)``\n", " that performs ``n_mc_steps`` Widom particle insertions every ``n_md_steps`` MD steps in a loop\n", " that repeats ``sample_size`` times and returns the chemical potential and its error as a tuple via\n", @@ -471,6 +478,7 @@ "a logarithmically scaled x-axis.\n", "\n", "**Exercise:**\n", + "\n", "* Explain the observed behaviour qualitatively\n", "* How do you expect the excess chemical potential to behave in the limit $c_{\\mathrm{salt}}\\rightarrow 0$ mol/l?" ] @@ -524,9 +532,11 @@ "$B \\simeq 1.0$ and $C = 0.2$ in reduced units for NaCl in an aqueous solution at 25°C.\n", "\n", "**Exercise:**\n", + "\n", "* Compare your simulation results with the Debye-Hückel theory and the Davies equation by plotting all three curves in a single plot\n", "\n", "**Hint:**\n", + "\n", "* re-use the code from the previous figure\n", "* create a logarithmic concentration range from $10^{-4}$ to $10^{0}$ mol/l with ``np.logspace(-4, 0.0, num=500, base=10)`` to plot the analytical solutions" ]