Merge pull request #706 from SciML/general_doc_update

TorkelE · web-flow · commit 524489a25136 · 2023-10-28T09:26:40.000-04:00
General doc update
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -19,7 +19,7 @@ StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 
 [compat]
-BifurcationKit = "0.2.4"
+BifurcationKit = "0.3"
 Catalyst = "13"
 DifferentialEquations = "7.7"
 Distributions = "0.25"
diff --git a/docs/src/catalyst_applications/advanced_simulations.md b/docs/src/catalyst_applications/advanced_simulations.md
@@ -401,3 +401,8 @@ species we wish to plot. Here, we plot the solution in `(X,Y)` space:
 ```@example ex4
 plot(sol; idxs=(:X, :Y))
 ```
+
+---
+## References
+[^1]: [DifferentialEquations.jl online documentation.](https://docs.sciml.ai/DiffEqDocs/stable/)
+[^2]: [Chris Rackauckas, Qing Nie, *DifferentialEquations.jl – A Performant and Feature-Rich Ecosystem for Solving Differential Equations in Julia*, Journal of Open Resource Software (2017).](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.151)
diff --git a/docs/src/catalyst_applications/bifurcation_diagrams.md b/docs/src/catalyst_applications/bifurcation_diagrams.md
@@ -72,7 +72,7 @@ We also bundle the information we have compiled so far into a
 using BifurcationKit, Plots, LinearAlgebra, Setfield
 
 bprob = BifurcationProblem(F, oprob.u0, oprob.p, (@lens _[bif_idx]);
-                           recordFromSolution = (x, p) -> x[plot_idx], J = J)
+                           record_from_solution = (x, p) -> x[plot_idx], J = J)
 nothing   # hide
 ```
 Next, we need to specify the input options for the pseudo-arclength continuation
@@ -81,10 +81,10 @@ method (PACM) which produces the diagram.
 bopts = ContinuationPar(dsmax = 0.05,          # Max arclength in PACM.
                         dsmin = 1e-4,          # Min arclength in PACM.
                         ds = 0.001,            # Initial (positive) arclength in PACM.
-                        maxSteps = 100000,     # Max number of steps.
-                        pMin = p_span[1],      # Min p-val (if hit, the method stops).
-                        pMax = p_span[2],      # Max p-val (if hit, the method stops).
-                        detectBifurcation = 3) # Value in {0,1,2,3}
+                        max_steps = 100000,     # Max number of steps.
+                        p_min = p_span[1],      # Min p-val (if hit, the method stops).
+                        p_max = p_span[2],      # Max p-val (if hit, the method stops).
+                        detect_bifurcation = 3) # Value in {0,1,2,3}
 nothing   # hide
 ```
 Here `detectBifurcation` determines to what extent bifurcation points are
@@ -110,3 +110,25 @@ branches are connected. However, BifurcationKit.jl is a very powerful package
 capable of a lot more. For more details, please see that package's
 documentation:
 [BifurcationKit.jl](https://bifurcationkit.github.io/BifurcationKitDocs.jl/stable/).
+
+---
+## [Citation](@id bifurcation_kit_citation)
+If you use this functionality in your research, please cite the following paper to support the author of the BifurcationKit package:
+```
+@misc{veltz:hal-02902346,
+  title = {{BifurcationKit.jl}},
+  author = {Veltz, Romain},
+  url = {https://hal.archives-ouvertes.fr/hal-02902346},
+  institution = {{Inria Sophia-Antipolis}},
+  year = {2020},
+  month = Jul,
+  keywords = {pseudo-arclength-continuation ; periodic-orbits ; floquet ; gpu ; bifurcation-diagram ; deflation ; newton-krylov},
+  pdf = {https://hal.archives-ouvertes.fr/hal-02902346/file/354c9fb0d148262405609eed2cb7927818706f1f.tar.gz},
+  hal_id = {hal-02902346},
+  hal_version = {v1},
+}
+```
+
+---
+## References
+[^1]: [Yuri A. Kuznetsov, *Elements of Applied Bifurcation Theory*, Springer (2023).](https://link.springer.com/book/10.1007/978-3-031-22007-4)
diff --git a/docs/src/catalyst_applications/homotopy_continuation.md b/docs/src/catalyst_applications/homotopy_continuation.md
@@ -9,10 +9,10 @@ integer Hill exponents). The roots of these can reliably be found through a
 *homotopy continuation* algorithm. This is implemented in Julia through the
 [HomotopyContinuation.jl](https://www.juliahomotopycontinuation.org/) package.
 
-Catalyst contains a special homotopy continuation extension that is loaded whenever HomotopyContinuation.jl is. This exports a single function, `hc_steady_states`, that can be used to find the steady states of any `ReactionSystem` structure. If you use this in your research, please [cite the HomotopyContinuation.jl](@ref homotopy_continuation_citation) and [Catalyst.jl]() publications.
+Catalyst contains a special homotopy continuation extension that is loaded whenever HomotopyContinuation.jl is. This exports a single function, `hc_steady_states`, that can be used to find the steady states of any `ReactionSystem` structure. If you use this in your research, please [cite the HomotopyContinuation.jl](@ref homotopy_continuation_citation) and [Catalyst.jl](@ref catalyst_citation) publications.
 
 ## Basic example
-For this tutorial, we will use a model from Wilhem (2009)[^1] (which
+For this tutorial, we will use a model from Wilhelm (2009)[^1] (which
 demonstrates bistability in a small chemical reaction network). We declare the
 model and the parameter set for which we want to find the steady states:
 ```@example hc1
@@ -54,16 +54,15 @@ Catalyst allows the conservation laws of such systems to be computed using the `
 ```@example hc3
 ps = [:k1 => 2.0, :k2 => 1.0]
 u0 = [:X1 => 1.0, :X2 => 1.0]
-hc_steady_states(wilhelm_2009_model, ps; u0)
-
+hc_steady_states(two_state_model, ps; u0)
 ```
 
 ## Final notes
 - `hc_steady_states` supports any systems where all rates are systems of rational polynomials (such as Hill functions with integer Hill coefficients).
 - When providing initial conditions to compute conservation laws, values are only required for those species that are part of conserved quantities. If this set of species is unknown, it is recommended to provide initial conditions for all species. 
 - Additional arguments provided to `hc_steady_states` are automatically passed to HomotopyContinuation's `solve` command. Use e.g. `show_progress=false` to disable the progress bar.
----
 
+---
 ## [Citation](@id homotopy_continuation_citation)
 If you use this functionality in your research, please cite the following paper to support the authors of the HomotopyContinuation package:
 ```
@@ -77,8 +76,9 @@ If you use this functionality in your research, please cite the following paper
 }
 ```
 
+---
 ## References
 [^1]: [Thomas Wilhelm, *The smallest chemical reaction system with bistability*, BMC Systems Biology (2009).](https://bmcsystbiol.biomedcentral.com/articles/10.1186/1752-0509-3-90)
 [^2]: [Paul Breiding, Sascha Timme, *HomotopyContinuation.jl: A Package for Homotopy Continuation in Julia*, International Congress on Mathematical Software (2018).](https://link.springer.com/chapter/10.1007/978-3-319-96418-8_54)
-[^3:] [Andrew J Sommese, Charles W Wampler *The Numerical Solution of Systems of Polynomials Arising in Engineering and Science*, World Scientific (2005).](https://www.worldscientific.com/worldscibooks/10.1142/5763#t=aboutBook)
-[^4:] [Daniel J. Bates, Paul Breiding, Tianran Chen, Jonathan D. Hauenstein, Anton Leykin, Frank Sottile, *Numerical Nonlinear Algebra*, arXiv (2023).](https://arxiv.org/abs/2302.08585)
+[^3]: [Andrew J Sommese, Charles W Wampler *The Numerical Solution of Systems of Polynomials Arising in Engineering and Science*, World Scientific (2005).](https://www.worldscientific.com/worldscibooks/10.1142/5763#t=aboutBook)
+[^4]: [Daniel J. Bates, Paul Breiding, Tianran Chen, Jonathan D. Hauenstein, Anton Leykin, Frank Sottile, *Numerical Nonlinear Algebra*, arXiv (2023).](https://arxiv.org/abs/2302.08585)
diff --git a/docs/src/example_networks/smoluchowski_coagulation_equation.md b/docs/src/example_networks/smoluchowski_coagulation_equation.md
@@ -131,6 +131,6 @@ For the **additive kernel** we find
 
 ---
 ## References
-1. [https://en.wikipedia.org/wiki/Smoluchowski\_coagulation\_equation](https://en.wikipedia.org/wiki/Smoluchowski_coagulation_equation)
-2. Scott, W. T. (1968). Analytic Studies of Cloud Droplet Coalescence I, Journal of Atmospheric Sciences, 25(1), 54-65. Retrieved Feb 18, 2021, from https://journals.ametsoc.org/view/journals/atsc/25/1/1520-0469\_1968\_025\_0054\_asocdc\_2\_0\_co\_2.xml
-3. Ian J. Laurenzi, John D. Bartels, Scott L. Diamond, A General Algorithm for Exact Simulation of Multicomponent Aggregation Processes, Journal of Computational Physics, Volume 177, Issue 2, 2002, Pages 418-449, ISSN 0021-9991, https://doi.org/10.1006/jcph.2002.7017.
+[^1]: [https://en.wikipedia.org/wiki/Smoluchowski\_coagulation\_equation](https://en.wikipedia.org/wiki/Smoluchowski_coagulation_equation)
+[^2]: Scott, W. T. (1968). Analytic Studies of Cloud Droplet Coalescence I, Journal of Atmospheric Sciences, 25(1), 54-65. Retrieved Feb 18, 2021, from https://journals.ametsoc.org/view/journals/atsc/25/1/1520-0469\_1968\_025\_0054\_asocdc\_2\_0\_co\_2.xml
+[^3]: Ian J. Laurenzi, John D. Bartels, Scott L. Diamond, A General Algorithm for Exact Simulation of Multicomponent Aggregation Processes, Journal of Computational Physics, Volume 177, Issue 2, 2002, Pages 418-449, ISSN 0021-9991, https://doi.org/10.1006/jcph.2002.7017.
diff --git a/docs/src/introduction_to_catalyst/catalyst_for_new_julia_users.md b/docs/src/introduction_to_catalyst/catalyst_for_new_julia_users.md
@@ -185,3 +185,8 @@ plot(sol)
 ---
 ## Feedback
 If you are a new Julia user who has used this tutorial, and there was something you struggled with or would have liked to have explained better, please [raise an issue](https://github.com/SciML/Catalyst.jl/issues). That way, we can continue improving this tutorial.
+
+---
+## References
+[^1]: [Jeff Bezanson, Alan Edelman, Stefan Karpinski, Viral B. Shah, *Julia: A Fresh Approach to Numerical Computing*, SIAM Review (2017).](https://epubs.siam.org/doi/abs/10.1137/141000671)
+[^2]: [Torkel E. Loman, Yingbo Ma, Vasily Ilin, Shashi Gowda, Niklas Korsbo, Nikhil Yewale, Chris Rackauckas, Samuel A. Isaacson, *Catalyst: Fast and flexible modeling of reaction networks*, PLOS Computational Biology (2023).](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530)
diff --git a/docs/src/introduction_to_catalyst/introduction_to_catalyst.md b/docs/src/introduction_to_catalyst/introduction_to_catalyst.md
@@ -346,3 +346,7 @@ and the ODE model
    [`ODEProblem`s](https://mtk.sciml.ai/dev/systems/ODESystem/#DiffEqBase.ODEProblem)
    and
    [`SDEProblem`s](https://mtk.sciml.ai/dev/systems/SDESystem/#DiffEqBase.SDEProblem).
+
+---
+## References
+[^1]: [Torkel E. Loman, Yingbo Ma, Vasily Ilin, Shashi Gowda, Niklas Korsbo, Nikhil Yewale, Chris Rackauckas, Samuel A. Isaacson, *Catalyst: Fast and flexible modeling of reaction networks*, PLOS Computational Biology (2023).](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530)
