Formatting and Read through

docs/_toc.yml

@@ -13,19 +13,21 @@ parts:
   - file: examples/distribution_evolution
   - file: examples/distribution_ambient
   - file: examples/ionparticle_coagulation
-  - file: examples/particula_data
+  - file: examples/streamlake/particula_data
     sections:
-    - file: examples/loading_data_part1
-    - file: examples/loading_data_part2
-    - file: examples/loading_data_part3
-    - file: examples/loading_data_part4
-    - file: examples/stream_stats_part1
-    - file: examples/stream_stats_size_distribution_part2
+    - file: examples/streamlake/loading_data_part1
+    - file: examples/streamlake/loading_data_part2
+    - file: examples/streamlake/loading_data_part3
+    - file: examples/streamlake/loading_data_part4
+    - file: examples/streamlake/stream_stats_part1
+    - file: examples/streamlake/stream_stats_size_distribution_part2
   - file: examples/wall_loss_section
     sections:
     - file: examples/chamber_smps_data
-  - file: examples/activity_part1
-  - file: examples/equilibria_part1
+  - file: examples/equilibria/equilibria_intro
+    sections:
+    - file: examples/equilibria/activity_part1
+    - file: examples/equilibria/equilibria_part1
 - caption: Documentation
   numbered: false
   chapters:

docs/examples/equilibria/equilibria_intro.md

@@ -0,0 +1,27 @@
+# Equilibria of Aerosols
+
+## What is Equilibria?
+
+Equilibria, a fundamental concept in physical chemistry, refers to the state where the concentrations of reactants and products in a chemical reaction remain constant over time. In the context of aerosol science, equilibria are essential in understanding how aerosol particles interact with their environment, particularly with respect to liquid and vapor phases. This balance is crucial in predicting how aerosols behave under different atmospheric conditions.
+
+## Why is Equilibria Important?
+
+Studying equilibria in aerosol systems is vital for several reasons:
+
+1. **Environmental Impact**: Aerosols play a significant role in air quality and climate change. Understanding their equilibrium behavior helps in assessing their environmental impact, such as their role in cloud formation and solar radiation scattering.
+
+2. **Health Implications**: Aerosols affect human health, especially in terms of respiratory issues. Knowledge of equilibrium states helps in evaluating exposure risks and designing mitigation strategies.
+
+3. **Atmospheric Chemistry**: Equilibria studies contribute to our understanding of atmospheric chemistry, particularly in the formation and transformation of aerosols.
+
+## How Does Equilibria Relate to These Notebooks?
+
+The notebooks presented here are dedicated to exploring various aspects of equilibria in aerosol science:
+
+1. **Activity Coefficients and Phase Behavior**: By calculating activity coefficients, we can predict how different components of aerosols partition between liquid and vapor phases. This is crucial in understanding the composition and concentration of aerosols under varying atmospheric conditions.
+
+2. **Liquid-Vapor Equilibrium**: The notebook delves into the equilibrium compositions of liquid-vapor mixtures, highlighting the role of relative humidity (RH) in shaping aerosol behavior.
+
+3. **Practical Applications**: Through examples and simulations, these notebooks provide practical insights into real-world scenarios, enhancing our understanding of aerosols in environmental and health contexts.
+
+Overall, the notebooks serve as an interactive platform to explore and understand the complex yet fascinating world of equilibria in aerosol science. Whether you're a student, researcher, or enthusiast, these materials offer valuable insights into the dynamic equilibrium processes that govern aerosol behavior in our atmosphere.

docs/examples/equilibria_part1.ipynb → docs/examples/equilibria/equilibria_part1.ipynb

@@ -6,8 +6,7 @@
    "source": [
     "# Liquid Vapor Equilibrium\n",
     "\n",
-    "Using the activity coefficient model, we can now calculate the equilibrium composition of a liquid-vapor mixture.  We consider just an\n",
-    "arbitrary organic volatility distribution to show the steps.\n"
+    "This notebook explores the calculation of equilibrium composition in liquid-vapor mixtures, a crucial concept in aerosol science and environmental studies. We utilize an activity coefficient model to understand how different volatile organic compounds distribute between the liquid and vapor phases. This analysis is particularly important for predicting aerosol behavior and understanding atmospheric processes."
    ]
   },
   {
@@ -16,65 +15,65 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# import libraries\n",
-    "import matplotlib.pyplot as plt\n",
-    "import numpy as np\n",
-    "from particula.activity import species_density\n",
+    "# Importing necessary libraries\n",
+    "import matplotlib.pyplot as plt  # For creating plots and visualizations\n",
+    "import numpy as np  # For numerical operations\n",
+    "from particula.activity import species_density  # For calculating species density\n",
+    "# For partitioning calculations in liquid-vapor equilibrium\n",
     "from particula.equilibria import partitioning"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Setup the system\n",
+    "## Setup the System\n",
     "\n",
-    "- c_star_j_dry: the volatility distribution of the organics in the dry air (can calculate from the vapor pressure)\n",
-    "- concentration_organic_matter: is the vapor+liquid concentration of the organics in the system\n",
-    "- oxygen2carbon: is the oxygen to carbon ratio of the organics in the system\n",
-    "- molar_mass: is the molar mass of the organics in the system\n",
+    "To simulate the liquid-vapor equilibrium, we define several key parameters:\n",
+    "- `c_star_j_dry`: Represents the volatility distribution of organic compounds in dry air, calculable from vapor pressure.\n",
+    "- `concentration_organic_matter`: The combined concentration of vapor and liquid organic matter in the system.\n",
+    "- `oxygen2carbon`: The ratio of oxygen to carbon in the organic compounds, crucial for characterizing their chemical nature.\n",
+    "- `molar_mass`: The molar mass of the organic compounds.\n",
     "\n",
-    "We'll use this infromation to get the denisty of the organics in the system."
+    "These parameters help us determine the density of organics in the system, a vital step in understanding their distribution between phases.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
-    "c_star_j_dry = [1e-6, 1e-4, 1e-1, 1e2, 1e4]  # ug/m3\n",
-    "concentration_organic_matter = [1, 5, 10, 15, 10]  # ug/m3\n",
-    "oxygen2carbon = np.array([0.2, 0.3, 0.5, 0.4, 0.4])\n",
+    "# Defining system parameters\n",
+    "c_star_j_dry = [1e-6, 1e-4, 1e-1, 1e2, 1e4]  # Volatility distribution in ug/m3\n",
+    "# Total concentration in ug/m3\n",
+    "concentration_organic_matter = [1, 5, 10, 15, 10]\n",
+    "oxygen2carbon = np.array([0.2, 0.3, 0.5, 0.4, 0.4])  # Oxygen to carbon ratios\n",
     "\n",
-    "molar_mass = np.array([200, 200, 200, 200, 200])  # g/mol\n",
-    "\n",
-    "water_activity_desired = np.array([0.8])\n",
-    "\n",
-    "molar_mass_ratio = 18.015 / np.array(molar_mass)\n",
+    "molar_mass = np.array([200, 200, 200, 200, 200])  # Molar mass in g/mol\n",
+    "water_activity_desired = np.array([0.8])  # Desired water activity\n",
+    "molar_mass_ratio = 18.015 / np.array(molar_mass)  # Molar mass ratio\n",
     "\n",
+    "# Calculate the density of organic compounds\n",
     "density = species_density.organic_array(\n",
-    "    molar_mass=molar_mass,\n",
-    "    oxygen2carbon=oxygen2carbon,\n",
+    "    molar_mass,\n",
+    "    oxygen2carbon,\n",
     "    hydrogen2carbon=None,\n",
-    "    nitrogen2carbon=None,\n",
-    ")"
+    "    nitrogen2carbon=None)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Calculate the activity coefficients\n",
+    "## Calculate the Activity Coefficients\n",
     "\n",
-    "For equilibrium, we do not need all the returns from `activity.binary_activity`, so \n",
-    "`partitioning.get_properties_for_liquid_vapor_equilibrium` is a wrapper that just returns the activity coefficients,\n",
-    "mass fractions, and the two phase q (alpha-beta) values."
+    "The next step involves calculating the activity coefficients, which are pivotal in determining how the organic compounds distribute between the liquid and vapor phases. We use the `partitioning.get_properties_for_liquid_vapor_equilibrium` function, a specialized tool that simplifies the process by returning only the essential properties: activity coefficients, mass fractions, and the two-phase *q* values for the alpha-beta equilibrium.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [
     {
@@ -87,6 +86,7 @@
     }
    ],
    "source": [
+    "# Calculate the properties needed for liquid-vapor partitioning\n",
     "gamma_organic_ab, mass_fraction_water_ab, q_ab = \\\n",
     "    partitioning.get_properties_for_liquid_vapor_partitioning(\n",
     "        water_activity_desired=water_activity_desired,\n",
@@ -95,7 +95,7 @@
     "        density=density,\n",
     "    )\n",
     "\n",
-    "# optimize the partition coefficients\n",
+    "# The optimization the partition coefficients, i.e. the partitioning calculation\n",
     "alpha_opt, beta_opt, system_opt, fit_result = \\\n",
     "    partitioning.liquid_vapor_partitioning(\n",
     "        c_star_j_dry=c_star_j_dry,\n",
@@ -115,35 +115,33 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Now with f(RH)\n",
+    "## Activity Coefficients as a Function of Relative Humidity (f(RH))\n",
     "\n",
-    "The whole point of the binary activity model is for interactions with water.\n",
-    "We can now calculate the activity coefficients as a function of RH or (water activity).\n",
-    "\n",
-    "We'll do that now by looping over a range of RH values and calculating the activity coefficients.\n"
+    "The binary activity model's key feature is its interaction with water, particularly through relative humidity (RH). Here, we will calculate how the activity coefficients vary as a function of RH. This is done by iterating over a range of RH values and computing the corresponding activity coefficients, providing insights into how atmospheric humidity influences the equilibrium behavior of the system."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "done\n"
+      "Calculation complete\n"
      ]
     }
    ],
    "source": [
-    "# and water concentration\n",
-    "\n",
+    "# Calculating activity coefficients across a range of RH values\n",
+    "# Range of water activity (RH/100)\n",
     "water_activity_curve = np.linspace(0.01, 0.99, 80)\n",
-    "totol_oa_concentration = np.empty([len(water_activity_curve), 1], dtype=float)\n",
+    "total_oa_concentration = np.empty([len(water_activity_curve), 1], dtype=float)\n",
     "water_concentration = np.empty([len(water_activity_curve), 1], dtype=float)\n",
     "\n",
     "for i, water_activity in enumerate(water_activity_curve):\n",
+    "    # Get properties for liquid-vapor partitioning at each RH value\n",
     "    gamma_organic_ab, mass_fraction_water_ab, q_ab = \\\n",
     "        partitioning.get_properties_for_liquid_vapor_partitioning(\n",
     "            water_activity_desired=water_activity,\n",
@@ -152,6 +150,7 @@
     "            density=density,\n",
     "        )\n",
     "\n",
+    "    # Optimize the partition coefficients for each RH value\n",
     "    alpha_opt, beta_opt, system_opt, fit_result = \\\n",
     "        partitioning.liquid_vapor_partitioning(\n",
     "            c_star_j_dry=c_star_j_dry,\n",
@@ -162,23 +161,26 @@
     "            q_ab=q_ab,\n",
     "            partition_coefficient_guess=None,\n",
     "        )\n",
-    "    \n",
-    "    # get the total organic concentration\n",
-    "    totol_oa_concentration[i] = system_opt[0]\n",
+    "\n",
+    "    # Record the total organic and water concentration\n",
+    "    total_oa_concentration[i] = system_opt[0]\n",
     "    water_concentration[i] = system_opt[1]\n",
-    "print('done')"
+    "\n",
+    "print('Calculation complete')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Now plot the results"
+    "## Plotting the Equilibrium Composition vs. Relative Humidity\n",
+    "\n",
+    "Now that we have calculated the equilibrium composition for a range of RH values, we will visualize these results. The plot will show how the total organic aerosol concentration and the water concentration in the aerosol vary with changing RH. This visualization is crucial for understanding the dynamic behavior of aerosols in different atmospheric humidity conditions."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
@@ -194,7 +196,7 @@
    ],
    "source": [
     "fig, ax = plt.subplots()\n",
-    "ax.plot(water_activity_curve, totol_oa_concentration,\n",
+    "ax.plot(water_activity_curve, total_oa_concentration,\n",
     "        label='total organic concentration', color='green')\n",
     "aw=ax.twinx()\n",
     "aw.plot(water_activity_curve, water_concentration,\n",
@@ -219,9 +221,7 @@
    "source": [
     "## Summary\n",
     "\n",
-    "We covered a lot of ground here.  We started with defining the system. We then used the binary activity model to calculate\n",
-    "the activity coefficients as a function of RH.  We then used those activity coefficients to calculate the equilibrium\n",
-    "composition of the liquid and vapor phases.  We then plotted the results."
+    "In this notebook, we have journeyed through the process of defining a liquid-vapor equilibrium system and employing the binary activity model to calculate activity coefficients as a function of relative humidity (RH). We then used these coefficients to determine the equilibrium composition of the liquid and vapor phases. Finally, the results were visualized to demonstrate the impact of RH on aerosol behavior, which is essential for understanding atmospheric aerosol dynamics and their environmental implications.\n"
    ]
   }
  ],