misc improvements

Author: TorkelE

docs/src/catalyst_functionality/chemistry_related_functionality.md

@@ -2,10 +2,10 @@
 
 While Catalyst has primarily been designed around the modelling of biological systems, reaction network models are also common across chemistry. This section describes two types of functionality, that while of general interest, should be especially useful in the modelling of chemical systems.
 - The `@compound` option, allowing the user to designate that a specific species is composed of certain subspecies.
-- The `balance_reaction` function enabling the user to balance a reactions so the same number of compounds occur on both sides.
+- The `balance_reaction` function enabling the user to balance a reaction so the same number of components occur on both sides.
 
 ## Modelling with compound species
-Defining compound species is currently only supported for [programmatic construction](@ref programmatic_CRN_construction) of reactions and reaction network models. To create a compound species, use the `@compound` macro, first designating the compound, followed by its components (and stoichiometries). In this example, we will create a CO₂ compound species, consisting of 1 C species and 2 O species. First we create species corresponding to the components:
+Defining compound species is currently only supported for [programmatic construction](@ref programmatic_CRN_construction) of reactions and reaction network models. To create a compound species, use the `@compound` macro, first designating the compound, followed by its components (and stoichiometries). In this example, we will create a CO₂ compound species, consisting of one C species and two O species. First, we create species corresponding to the components:
 ```@example chem1
 @variables t
 @species C(t) O(t) 
@@ -14,11 +14,11 @@ Next, we create the `CO2` compound:
 ```@example chem1
 @compound CO2(t) = C + 2O
 ```
-Here, the compound is the first argument to the macro, followed by its component. The `(t)` indicates that `CO2` is a time-dependant variable. Components with non-unitary stoichiometry have this value written before the component (generally, the rules for designating the components of a compounds are identical to hose of designating the substrates or products of a reaction). The created compound, `CO2`, is a species in every sense, and can be used wherever e.g. `C` could be used:
+Here, the compound is the first argument to the macro, followed by its component. The `(t)` indicates that `CO2` is a time dependant species. Components with non-unitary stoichiometries have this value written before the component (generally, the rules for designating the components of a compound are identical to those of designating the substrates or products of a reaction). The created compound, `CO2`, is a species in every sense, and can be used wherever e.g. `C` can be used:
 ```@example chem1
 isspecies(CO2)
 ```
-However, in its metadata is stored the information of its components, which can be retrieved using the `components` (returning a vector of its component species) and `coefficients` (returning a vector with each component's stoichiometry) functions:
+In its metadata, however, is stored information of its components, which can be retrieved using the `components` (returning a vector of its component species) and `coefficients` (returning a vector with each component's stoichiometry) functions:
 ```@example chem1
 components(CO2)
 ```
@@ -41,7 +41,7 @@ Compound components that are also compounds are allowed, e.g. we can create a ca
 @compound H2CO3(t) = CO2 + H2O
 ```
 
-When multiple compounds are created, they can be created simultaneously using the `@compounds` macro, e.g. the previous code-block could have been executed using:
+When multiple compounds are created, they can be created simultaneously using the `@compounds` macro, e.g. the previous code-block can be re-written as:
 ```@example chem1
 @species H(t)
 @compounds begin
@@ -50,18 +50,18 @@ When multiple compounds are created, they can be created simultaneously using th
 end
 ```
 
-One use defining a species as a compound is that they can be used to balance reactions to that the number of compounds are the same on both side.
+One use of defining a species as a compound is that they can be used to balance reactions to that the number of compounds are the same on both sides.
 
 ## Balancing chemical reactions
-Catalyst provides the `balance_reaction` function, which takes a reaction, and returns a balanced version. E.g. let us consider a reaction when carbon dioxide is formed from carbon and oxide `C + O --> CO2`. Here, `balance_reaction` enable us to find coefficients creating a balanced reaction (in this case, where the number of carbon and oxygen atoms are teh same on both sides). To demonstrate, we first created the unbalanced reactions:
+Catalyst provides the `balance_reaction` function, which takes a reaction, and returns a balanced version. E.g. let us consider a reaction when carbon dioxide is formed from carbon and oxide `C + O --> CO2`. Here, `balance_reaction` enables us to find coefficients creating a balanced reaction (in this case, where the number of carbon and oxygen atoms are the same on both sides). To demonstrate, we first created the unbalanced reactions:
 ```@example chem1
 rx = @reaction k, C + O --> $CO2
 ```
-Here, we set a reaction rate `k` (which is not involved in the reaction balancing). We also use interpolation of `CO2`, ensuring that the `CO2` used in the reaction is the same one we previously defined as a compound of `C` and `O`. Next, we call the `balance_reaction` function
+Here, the reaction rate (`k`) is not involved in the reaction balancing. We use interpolation for `CO2`, ensuring that the `CO2` used in the reaction is the same one we previously defined as a compound of `C` and `O`. Next, we call the `balance_reaction` function
 ```@example chem1
 balance_reaction(rx)
 ```
-which correctly finds the (rather trivial) solution `C + 2O --> CO2`. Here we note that `balance_reaction` actually returns a vector. The reason is that the reaction balancing problem may have several solutions. Typically, there is only a single solution (in which case this is the vector's only element). 
+which correctly finds the (rather trivial) solution `C + 2O --> CO2`. Here we note that `balance_reaction` actually returns a vector. The reason is that the reaction balancing problem may have several solutions. Typically, there is only a single solution (in which case this is the vector's only element). No, or an infinite number of, solutions is also possible.
 
 Let us consider a more elaborate example, the reaction between ammonia (NH₃) and oxygen (O₂) to form nitrogen monoxide (NO) and water (H₂O). Let us first create the components and the unbalanced reaction:
 ```@example chem2
@@ -76,7 +76,7 @@ using Catalyst # hide
 end
 unbalanced_reaction = @reaction k, $NH3 + $O2 --> $NO + $H2O
 ```
-We can now created a balanced version (where the amount of H, N, and O is the same on both sides):
+We can now create a balanced version (where the amount of H, N, and O is the same on both sides):
 ```@example chem2
 balanced_reaction = balance_reaction(unbalanced_reaction)[1]
 ```

src/chemistry_functionality.jl

@@ -12,7 +12,7 @@ Symbolics.option_to_metadata_type(::Val{:coefficients}) = CompoundCoefficients
 """
     @compound
 
-Macro that creates a compound species, which is composed of smaller constituent species.
+Macro that creates a compound species, which is composed of smaller component species.
 
 Example:
 ```julia
@@ -22,7 +22,7 @@ Example:
 ```
 
 Notes: 
-- The constituent species must be defined before using the `@compound` macro.
+- The component species must be defined before using the `@compound` macro.
 """
 macro compound(expr)
     make_compound(MacroTools.striplines(expr))
@@ -62,7 +62,7 @@ end
 """
     @compounds
 
-Macro that creates several compound species, which each is composed of smaller constituent species. Uses the same syntax as `@compound`, but with one compound species one each line.
+Macro that creates several compound species, which each is composed of smaller component species. Uses the same syntax as `@compound`, but with one compound species one each line.
 
 Example:
 ```julia
@@ -77,7 +77,7 @@ end
 ```
 
 Notes: 
-- The constituent species must be defined before using the `@compound` macro.
+- The component species must be defined before using the `@compound` macro.
 """
 macro compounds(expr)
     make_compounds(MacroTools.striplines(expr))
@@ -132,6 +132,7 @@ function component_coefficients(s)
     return [c => co for (c, co) in zip(components(s), coefficients(s))]
 end
 
+
 ### Reaction Balancing Functionality ###
 
 # Reaction balancing error.