Merge pull request #200 from sandialabs/docs

docs update

docs/source/main.bib

@@ -67,7 +67,7 @@ @article{buche2022freely
 }
 
 @article{buche2020statistical,
-  title={Statistical mechanical constitutive theory of polymer networks: The inextricable links between distribution, behavior, and ensemble},
+  title={{Statistical mechanical constitutive theory of polymer networks: The inextricable links between distribution, behavior, and ensemble}},
   author={Buche, Michael R. and Silberstein, Meredith N.},
   journal={Physical Review E},
   shortjournal={Phys. Rev. E},
@@ -96,7 +96,17 @@ @phdthesis{buche2021fundamental
   author={Buche, Michael Robert},
   year={2021},
   school={Cornell University},
-  doi={https://doi.org/10.7298/th3r-n996}
+  doi={10.7298/th3r-n996}
+}
+
+@article{buche2023modeling,
+  title={Modeling single-molecule stretching experiments using statistical thermodynamics},
+  author={Buche, Michael R. and Rimsza, Jessica M.},
+  journal={arXiv},
+  volume={2309},
+  number={01009},
+  year={2023},
+  doi={10.48550/arXiv.2309.01009}
 }
 
 @article{balabaev2009extension,

docs/source/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/strong_potential.rst

@@ -16,3 +16,10 @@ FJC model thermodynamics (modified canonical/asymptotic/strong potential)
    .. automethod:: nondimensional_helmholtz_free_energy_per_link(nondimensional_potential_distance, nondimensional_potential_stiffness, temperature)
    .. automethod:: nondimensional_relative_helmholtz_free_energy(nondimensional_potential_distance, nondimensional_potential_stiffness)
    .. automethod:: nondimensional_relative_helmholtz_free_energy_per_link(nondimensional_potential_distance, nondimensional_potential_stiffness)
+
+.. raw::
+ html
+
+   <hr>
+
+.. footbibliography::

docs/source/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/weak_potential.rst

@@ -20,3 +20,10 @@ FJC model thermodynamics (modified canonical/asymptotic/weak potential)
    .. automethod:: nondimensional_gibbs_free_energy_per_link(nondimensional_potential_distance, nondimensional_potential_stiffness, temperature)
    .. automethod:: nondimensional_relative_gibbs_free_energy(nondimensional_potential_distance, nondimensional_potential_stiffness)
    .. automethod:: nondimensional_relative_gibbs_free_energy_per_link(nondimensional_potential_distance, nondimensional_potential_stiffness)
+
+.. raw::
+ html
+
+   <hr>
+
+.. footbibliography::

docs/source/physics/single_chain/fjc/thermodynamics/modified_canonical/example_asymptotic.ipynb

@@ -9,7 +9,9 @@
     "\n",
     "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/sandialabs/Polymers/main?labpath=docs%2Fsource%2F%2Fphysics%2Fsingle_chain%2Ffjc%2Fthermodynamics%2Fmodified_canonical%2Fexample_asymptotic.ipynb)\n",
     "\n",
-    "This example demonstrates the validity of the asymptotic approaches of approximating the thermodynamics of the freely-jointed chain (FJC) model in the modified canonical ensemble. To start, import and create an instance of the FJC model in the modified canonical ensemble:"
+    "This example demonstrates the validity of the asymptotic approaches of approximating the thermodynamics of the freely-jointed chain (FJC) model in the modified canonical ensemble. For more information, see [Buche and Rimsza, 2023](https://doi.org/10.48550/arXiv.2309.01009).\n",
+    "\n",
+    "To start, import and create an instance of the FJC model in the modified canonical ensemble:"
    ]
   },
   {

src/math/mod.rs

@@ -112,7 +112,7 @@ fn bessel_i0(x: &f64) -> f64
 {
     if x < &7.75
     {
-        let coefficients = vec![
+        let coefficients = [
             1.0,
             2.499_999_999_999_999e-1,
             2.777_777_777_777_822e-2,
@@ -134,7 +134,7 @@ fn bessel_i0(x: &f64) -> f64
     }
     else if x < &500.0
     {
-        let coefficients = vec![
+        let coefficients = [
              3.989_422_804_014_25e-1,
              4.986_778_506_049_619e-2,
              2.805_062_339_283_126e-2,
@@ -162,7 +162,7 @@ fn bessel_i0(x: &f64) -> f64
     }
     else
     {
-        let coefficients = vec![
+        let coefficients = [
             3.989_422_804_014_329e-1,
             4.986_778_504_914_345e-2,
             2.805_063_089_165_061e-2,
@@ -178,7 +178,7 @@ fn bessel_i1(x: &f64) -> f64
 {
     if x < &7.75
     {
-        let coefficients = vec![
+        let coefficients = [
             8.333_333_333_333_333e-2,
             6.944_444_444_444_341e-3,
             3.472_222_222_225_921e-4,
@@ -194,7 +194,7 @@ fn bessel_i1(x: &f64) -> f64
             1.332_898_928_162_29e-23
         ];
         let t = 0.25*x.powi(2);
-        let more_coefficients = vec![
+        let more_coefficients = [
             1.0,
             0.5,
             coefficients.iter().enumerate().map(|(i, c)| c*t.powi(i.try_into().unwrap())).sum::<f64>()
@@ -203,7 +203,7 @@ fn bessel_i1(x: &f64) -> f64
     }
     else if x < &500.0
     {
-        let coefficients = vec![
+        let coefficients = [
              3.989_422_804_014_406e-1,
             -1.496_033_551_613_111e-1,
             -4.675_104_253_598_537e-2,
@@ -231,7 +231,7 @@ fn bessel_i1(x: &f64) -> f64
     }
     else
     {
-        let coefficients = vec![
+        let coefficients = [
              3.989_422_804_014_314e-1,
             -1.496_033_551_467_584e-1,
             -4.675_105_322_571_775e-2,

src/physics/single_chain/fjc/thermodynamics/isometric/mod.jl

@@ -129,7 +129,7 @@ end
 
 """
 The expected nondimensional force ``\\eta`` as a function of the applied nondimensional end-to-end length per link ``\\gamma``,
-parameterized by the number of links ``N_b``,
+parameterized by the number of links ``N_b``, given by [Buche and Rimsza](https://doi.org/10.48550/arXiv.2309.01009) as
 
 ```math
 \\eta(\\gamma) = \\frac{\\partial\\vartheta}{\\partial\\gamma} = \\frac{1}{N_b\\gamma} + \\left(\\frac{1}{2} - \\frac{1}{N_b}\\right)\\frac{\\sum_{s=0}^{s_\\mathrm{max}}(-1)^s\\binom{N_b}{s}\\left(m - \\frac{s}{N_b}\\right)^{N_b - 3}}{\\sum_{s=0}^{s_\\mathrm{max}}(-1)^s\\binom{N_b}{s}\\left(m - \\frac{s}{N_b}\\right)^{N_b - 2}},

src/physics/single_chain/fjc/thermodynamics/isometric/py.rs

@@ -69,7 +69,7 @@ impl FJC
     {
         end_to_end_length.as_array().mapv(|end_to_end_length: f64| super::force(&self.number_of_links, &self.link_length, &end_to_end_length, &temperature)).into_pyarray(py)
     }
-    /// The expected nondimensional force as a function of the applied nondimensional end-to-end length per link,
+    /// The expected nondimensional force as a function of the applied nondimensional end-to-end length per link, given by :footcite:t:`buche2023modeling` as
     ///
     /// .. math::
     ///     \eta(\gamma) = \frac{\partial\vartheta}{\partial\gamma} = \frac{1}{N_b\gamma} + \left(\frac{1}{2} - \frac{1}{N_b}\right)\frac{\sum_{s=0}^{s_\mathrm{max}}(-1)^s\binom{N_b}{s}\left(m - \frac{s}{N_b}\right)^{N_b - 3}}{\sum_{s=0}^{s_\mathrm{max}}(-1)^s\binom{N_b}{s}\left(m - \frac{s}{N_b}\right)^{N_b - 2}},

src/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/strong_potential/mod.jl

@@ -110,7 +110,13 @@ end
 
 """
 The expected nondimensional force ``\\eta`` as a function of the applied nondimensional potential distance and nondimensional potential stiffness,
-parameterized by the number of links ``N_b``.
+parameterized by the number of links ``N_b``, given by [Buche and Rimsza](https://doi.org/10.48550/arXiv.2309.01009) as
+
+```math
+\\eta(\\gamma) = \\eta_0(\\gamma) - \\frac{1}{N_b\\varpi}\\left[\\eta_0(\\gamma)\\eta_0'(\\gamma) - \\frac{\\eta_0''(\\gamma)}{2N_b}\\right],
+```
+
+where ``\\eta_0(\\gamma)`` is the isometric mechanical response.
 
 $(TYPEDSIGNATURES)
 """

src/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/strong_potential/py.rs

@@ -59,7 +59,12 @@ impl FJC
     {
         potential_distance.as_array().mapv(|potential_distance: f64| super::force(&self.number_of_links, &self.link_length, &potential_distance, &potential_stiffness, &temperature)).into_pyarray(py)
     }
-    /// The expected nondimensional force as a function of the applied nondimensional potential distance and nondimensional potential stiffness.
+    /// The expected nondimensional force as a function of the applied nondimensional potential distance and nondimensional potential stiffness, given by :footcite:t:`buche2023modeling` as
+    ///
+    /// .. math::
+    ///     \eta(\gamma) = \eta_0(\gamma) - \frac{1}{N_b\varpi}\left[\eta_0(\gamma)\eta_0'(\gamma) - \frac{\eta_0''(\gamma)}{2N_b}\right],
+    ///
+    /// where :math:`\eta_0(\gamma)` is the isometric mechanical response.
     ///
     /// Args:
     ///     nondimensional_potential_distance (numpy.ndarray): The nondimensional potential distance.

src/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/weak_potential/mod.jl

@@ -200,7 +200,13 @@ end
 
 """
 The expected nondimensional end-to-end length ``\\gamma\\equiv\\xi/N_b\\ell_b`` as a function of the applied nondimensional potential distance and nondimensional potential stiffness,
-parameterized by the number of links ``N_b``.
+parameterized by the number of links ``N_b``, given by [Buche and Rimsza](https://doi.org/10.48550/arXiv.2309.01009) as
+
+```math
+\\gamma(\\eta) = \\gamma_0(\\eta)\\left[1 - N_b\\varpi\\gamma_0'(\\eta)\\right],
+```
+
+where ``\\gamma_0(\\eta)=\\mathcal{L}(\\eta)=\\coth(\\eta)-1/\\eta`` is the Langevin function.
 
 $(TYPEDSIGNATURES)
 """

src/physics/single_chain/fjc/thermodynamics/modified_canonical/asymptotic/weak_potential/py.rs

@@ -45,6 +45,16 @@ impl FJC
             number_of_links
         }
     }
+    /// The expected end-to-end length as a function of the applied potential distance, potential stiffness, and temperature.
+    ///
+    /// Args:
+    ///     potential_distance (numpy.ndarray): The potential distance.
+    ///     potential_stiffness (float): The potential stiffness.
+    ///     temperature (float): The temperature :math:`T`.
+    ///
+    /// Returns:
+    ///     numpy.ndarray: The end-to-end length :math:`\xi`.
+    ///
     pub fn end_to_end_length<'py>(&self, py: Python<'py>, potential_distance: PyReadonlyArrayDyn<f64>, potential_stiffness: f64, temperature: f64) -> &'py PyArrayDyn<f64>
     {
         potential_distance.as_array().mapv(|potential_distance: f64| super::end_to_end_length(&self.number_of_links, &self.link_length, &potential_distance, &potential_stiffness, &temperature)).into_pyarray(py)
@@ -76,7 +86,12 @@ impl FJC
     {
         nondimensional_potential_distance.as_array().mapv(|nondimensional_potential_distance: f64| super::nondimensional_end_to_end_length(&self.number_of_links, &nondimensional_potential_distance, &nondimensional_potential_stiffness)).into_pyarray(py)
     }
-    /// The expected nondimensional end-to-end length per link as a function of the applied nondimensional potential distance and nondimensional potential stiffness.
+    /// The expected nondimensional end-to-end length per link as a function of the applied nondimensional potential distance and nondimensional potential stiffness, given by :footcite:t:`buche2023modeling` as
+    ///
+    /// .. math::
+    ///     \gamma(\eta) = \gamma_0(\eta)\left[1 - N_b\varpi\gamma_0'(\eta)\right],
+    ///
+    /// where :math:`\gamma_0(\eta)=\mathcal{L}(\eta)=\coth(\eta)-1/\eta` is the Langevin function.
     ///
     /// Args:
     ///     nondimensional_potential_distance (numpy.ndarray): The nondimensional potential distance.
@@ -90,7 +105,7 @@ impl FJC
         nondimensional_potential_distance.as_array().mapv(|nondimensional_potential_distance: f64| super::nondimensional_end_to_end_length_per_link(&self.number_of_links, &nondimensional_potential_distance, &nondimensional_potential_stiffness)).into_pyarray(py)
     }
     /// The expected force as a function of the applied potential distance and potential stiffness.
-
+    ///
     /// Args:
     ///     potential_distance (numpy.ndarray): The potential distance.
     ///     potential_stiffness (float): The potential stiffness.