Update docs (#416)

Author: mkg33

README.md

@@ -6,7 +6,7 @@
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://mtk.sciml.ai/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://mtk.sciml.ai/dev/)
 
-ModelingToolkit.jl is a modeling framework for high performance symbolic-numeric computation 
+ModelingToolkit.jl is a modeling framework for high-performance symbolic-numeric computation
 in scientific computing  and scientific machine learning.
 It allows for users to give a high-level description of a model for
 symbolic preprocessing to analyze and enhance the model. ModelingToolkit can
@@ -18,11 +18,11 @@ to the model to make it easier for numerical solvers to handle.
 For information on using the package,
 [see the stable documentation](https://mtk.sciml.ai/stable/). Use the
 [in-development documentation](https://mtk.sciml.ai/dev/) for the version of
-the documentation which contains the un-released features.
+the documentation which contains the unreleased features.
 
-## High Level Examples
+## High-Level Examples
 
-First let's define a second order riff on the Lorenz equations, symbolically
+First, let's define a second order riff on the Lorenz equations, symbolically
 lower it to a first order system, symbolically generate the Jacobian function
 for the numerical integrator, and solve it.
 
@@ -59,8 +59,8 @@ using Plots; plot(sol,vars=(x,y))
 
 This automatically will have generated fast Jacobian functions, making
 it more optimized than directly building a function. In addition, we can then
-use ModelingToolkit to compose multiple ODE subsystems. Now let's define two
-interacting Lorenz equations and simulate the resulting Differential-Algebriac
+use ModelingToolkit to compose multiple ODE subsystems. Now, let's define two
+interacting Lorenz equations and simulate the resulting Differential-Algebraic
 Equation (DAE):
 
 ```julia

docs/src/IR.md

@@ -2,12 +2,12 @@
 
 ModelingToolkit IR, which falls under the `Expression` abstract type, mirrors
 the Julia AST but allows for easy mathematical manipulation by itself following
-mathematical semantics. The base of the IR is the `Variable` type which defines
+mathematical semantics. The base of the IR is the `Variable` type, which defines
 a symbolic variable. These variables are combined using `Operation`s, which are
 registered functions applied to the various variables. These `Operation`s then
 perform automatic tracing, so normal mathematical functions applied to an `Operation`
 generate a new `Operation`. For example, `op1 = x+y` is one `Operation` and
-`op2 = 2z` is another, and so `op1*op2` is another `Operation`. Then at the top,
+`op2 = 2z` is another, and so `op1*op2` is another `Operation`. Then, at the top,
 an `Equation`, normally written as `op1 ~ op2`, defines the symbolic equality
 between two operations.
 
@@ -24,7 +24,7 @@ Equation
 ### Function Registration
 
 The ModelingToolkit graph only allowed for registered Julia functions for the
-operations. All other functions are automatically traced down to registred
+operations. All other functions are automatically traced down to registered
 functions. By default, ModelingToolkit.jl pre-registers the common functions
 utilized in the AD package ruleset [DiffRules.jl](https://github.com/JuliaDiff/DiffRules.jl)
 and pre-defines their derivatives. However, the user can utilize the `@register`
@@ -36,8 +36,8 @@ macro to add their function to allowed functions of the computation graph.
 
 ### Derivatives and Differentials
 
-A `Differential(op)` is a partial derivative with respect to the operation `op`
-which can then be applied to some other operations. For example `D=Differential(t)`
+A `Differential(op)` is a partial derivative with respect to the operation `op`,
+which can then be applied to some other operations. For example, `D=Differential(t)`
 is what would commonly be referred to as `d/dt`, which can then be applied to
 other operations using its function call, so `D(x+y)` is `d(x+y)/dt`.
 
@@ -55,7 +55,7 @@ ModelingToolkit.jacobian
 ModelingToolkit.hessian
 ```
 
-Note that generation of sparse matrices simply follows from the Julian semantics
+Note that the generation of sparse matrices simply follows from the Julia semantics
 imbued on the IR, so `sparse(jac)` changes a dense Jacobian to a sparse Jacobian
 matrix.
 
@@ -64,7 +64,7 @@ matrix.
 There is a large amount of derivatives pre-defined by
 [DiffRules.jl](https://github.com/JuliaDiff/DiffRules.jl). Note that `Expression`
 types are defined as `<:Real`, and thus any functions which allow the use of real
-numbers can automatically be traced by the derivative mechanism. Thus for example:
+numbers can automatically be traced by the derivative mechanism. Thus, for example:
 
 ```julia
 f(x,y,z) = x^2 + sin(x+y) - z
@@ -86,7 +86,7 @@ ModelingToolkit.derivative(::typeof(my_function), args::NTuple{N,Any}, ::Val{i})
 ```
 
 where `i` means that it's the derivative of the `i`th argument. `args` is the
-array of arguments, so for example if your function is `f(x,t)` then `args = [x,t]`.
+array of arguments, so, for example, if your function is `f(x,t)`, then `args = [x,t]`.
 You should return an `Operation` for the derivative of your function.
 
 For example, `sin(t)`'s derivative (by `t`) is given by the following:
@@ -102,7 +102,7 @@ types. Most of the functionality comes by the `Expression` type obeying the
 standard mathematical semantics. For example, if one has `A` a matrix of
 `Expression`, then `A^2` calculates the `Expression`s for the squared matrix.
 In that sense, it is encouraged that one uses standard Julia for performing a
-lot of the manipulation on the IR, as for example calculating the sparse form
+lot of the manipulation on the IR, as, for example, calculating the sparse form
 of the matrix via `sparse(A)` is valid, legible, and easily understandable
 to all Julia programmers.
 
@@ -124,7 +124,7 @@ like those for differential equation solvers and optimization libraries.
 
 Additionally, the core compilation process of ModelingToolkit IR is `build_function`.
 `build_function` takes an operation or an `AbstractArray` of operations and
-generates a compile-able version of the model for numerical solvers.
+generates a compilable version of the model for numerical solvers.
 
 ```@docs
 build_function

docs/src/highlevel.md

@@ -1,17 +1,17 @@
 # High Level API
 
-The high level API allows modelers to interactively build models in a symbolic
+The high-level API allows modelers to interactively build models in a symbolic
 manner. It is designed as a semi-DSL for easily building large complex models
-and manipulating the models to generate optimal forms for utilizing in numerical
+and manipulating the models to generate optimal forms to be used in numerical
 methods.
 
 ## Examples
 
 ### Example 1: Symbolically Building an ODEProblem for DifferentialEquations.jl
 
-Let's build an ODE. First we define some variables. In a differential equation
+Let's build an ODE. First, we define some variables. In a differential equation
 system, we need to differentiate between our (dependent) variables
-and parameters. Therefore we label them as follows:
+and parameters. Therefore, we label them as follows:
 
 ```julia
 using ModelingToolkit
@@ -73,7 +73,7 @@ connections = [0 ~ lorenz1.x + lorenz2.y + sin(α*γ)]
 connected = ODESystem(connections,[α],[γ],systems=[lorenz1,lorenz2])
 ```
 
-which is now a differential-algebraic equation (DAE) of 7 variables which has
+which is now a differential-algebraic equation (DAE) of 7 variables, which has
 two independent Lorenz systems and an algebraic equation that determines `α`
 such that an implicit constraint holds. We can then define the resulting
 `ODEProblem` and send it over to DifferentialEquations.jl.
@@ -169,7 +169,7 @@ which gives:
       end)
 ```
 
-Now we can call `nlsolve` by enclosing our parameters into the functions:
+Now, we can call `nlsolve` by enclosing our parameters into the functions:
 
 ```julia
 using NLsolve
@@ -184,9 +184,9 @@ generate the function, i.e.:
 nlsys_func = generate_function(ns, [x,y,z], [σ,ρ,β], expression=Val{false})[2]
 ```
 
-which uses GeneralizedGenerated.jl to build a same world-age function on the fly without eval.
+which uses GeneralizedGenerated.jl to build the same world-age function on the fly without eval.
 
-## High Level API Documentation
+## High-Level API Documentation
 
 ```@docs
 @parameters
@@ -195,14 +195,14 @@ which uses GeneralizedGenerated.jl to build a same world-age function on the fly
 Base.:~(::Expression, ::Expression)
 ```
 
-## Additional High Level Explanations and Tips
+## Additional High-Level Explanations and Tips
 
 ### The Auto-Detecting System Constructors
 
-For the high level interface, the system constructors such as `ODESystem` have
-high level constructors which just take in the required equations and automatically
+For the high-level interface, the system constructors, such as `ODESystem`, have
+high-level constructors, which just take in the required equations and automatically
 parse the expressions to figure out the states and parameters of the system.
-The following high level constructors exist:
+The following high-level constructors exist:
 
 ```julia
 ODESystem(eqs)
@@ -211,7 +211,7 @@ NonlinearSystem(eqs)
 
 ### Direct Tracing
 
-Because the ModelingToolkit `Expression` types obey Julia-semantics, one can
+Because the ModelingToolkit `Expression` types obey Julia semantics, one can
 directly transform existing Julia functions into ModelingToolkit symbolic
 representations of the function by simply inputting the symbolic values into
 the function and using what is returned. For example, let's take the following
@@ -282,7 +282,7 @@ multithreadedjac = eval(ModelingToolkit.build_function(vec(jac),u,multithread=tr
 ### modelingtoolkitize
 
 For some `DEProblem` types, automatic tracing functionality is already included
-via the `modelingtoolkitize` function. Take for example the Robertson ODE
+via the `modelingtoolkitize` function. Take, for example, the Robertson ODE
 defined as an `ODEProblem` for DifferentialEquations.jl:
 
 ```julia
@@ -299,7 +299,7 @@ prob = ODEProblem(rober,[1.0,0.0,0.0],(0.0,1e5),(0.04,3e7,1e4))
 ```
 
 If we want to get a symbolic representation, we can simply call `modelingtoolkitize`
-on the `prob` which will return an `ODESystem`:
+on the `prob`, which will return an `ODESystem`:
 
 ```julia
 sys = modelingtoolkitize(prob)

docs/src/index.md

@@ -1,7 +1,7 @@
 # ModelingToolkit.jl
 
-ModelingToolkit.jl is a modeling language for high performance 
-symbolic-numeric computation in scientific computing  and scientific machine learning.
+ModelingToolkit.jl is a modeling language for high-performance
+symbolic-numeric computation in scientific computing and scientific machine learning.
 It allows for users to give a high-level description of a model for
 symbolic preprocessing to analyze and enhance the model. ModelingToolkit can
 automatically generate fast functions for model components like Jacobians
@@ -20,10 +20,10 @@ ModelingToolkit has 3 layers:
    ModelingToolkit models directly from Julia code.
 2. The `AbstractSystem` level. This is the level where content-dependent functionality
    is added, where models such an ordinary differential equation are represented.
-   At the system level there are *transformations* which take one system to
+   At the system level, there are *transformations* which take one system to
    another, and *targets* which output code for numerical solvers.
 3. The IR level, also referred to as the direct level. At this level, one
-   directly acts on arrays of `Equation`, `Operation` and `Variable` types to
+   directly acts on arrays of `Equation`, `Operation`, and `Variable` types to
    generate functions.
 
 Each level above is built on the level below, giving more context to allow for

docs/src/systems/AbstractSystem.md

@@ -13,7 +13,7 @@ Each `AbstractSystem` has lists of variables in context, such as distinguishing
 parameters vs states. In addition, an `AbstractSystem` also can hold other
 `AbstractSystem` types. Direct accessing of the values, such as `sys.states`,
 gives the immediate list, while the accessor functions `states(sys)` gives the
-total set which includes that of all systems held inside.
+total set, which includes that of all systems held inside.
 
 The values which are common to all `AbstractSystem`s are:
 
@@ -25,9 +25,9 @@ The values which are common to all `AbstractSystem`s are:
 ## Transformations
 
 Transformations are functions which send a valid `AbstractSystem` definition to
-another `AbstractSystem`. These are passes like optimizations (ex: Block-Lower
-Triangle transformations) or changes to the representation which allow for
-alternative numerical methods to be utilized on the model (ex: DAE index reduction).
+another `AbstractSystem`. These are passes, like optimizations (e.g., Block-Lower
+Triangle transformations), or changes to the representation, which allow for
+alternative numerical methods to be utilized on the model (e.g., DAE index reduction).
 
 ## Function Calculation and Generation
 
@@ -36,8 +36,8 @@ quantities to enhance the numerical methods applied to the resulting system.
 The calculations, like `calculate_jacobian`, generate ModelingToolkit IR for
 the Jacobian of the system, while the generations, like `generate_jacobian`,
 generate compiled output for the numerical solvers by applying `build_function`
-to the generated code. Additionally, many systems have function type outputs
-which cobble together the generation functionality for a system, for example
+to the generated code. Additionally, many systems have function-type outputs,
+which cobble together the generation functionality for a system, for example,
 `ODEFunction` can be used to generate a DifferentialEquations-based `ODEFunction`
 with compiled version of the ODE itself, the Jacobian, the mass matrix, etc.
 
@@ -63,6 +63,6 @@ which allow for directly generating the problem types required for numerical
 methods. The first argument is always the `AbstractSystem`, and the proceeding
 arguments match the argument order of their original constructors. Whenever an
 array would normally be provided, such as `u0` the initial condition of an
-`ODEProblem`, it is instead replaced with a variable map, i.e. an array of
-pairs `var=>value` which allows the user to designate the values without having
+`ODEProblem`, it is instead replaced with a variable map, i.e., an array of
+pairs `var=>value`, which allows the user to designate the values without having
 to know the order that ModelingToolkit is internally using.

docs/src/systems/ReactionSystem.md

@@ -1,6 +1,6 @@
 # ReactionSystem
 
-A `ReactionSystem` represents a system of chemical reactions. Conversions are provided to generate corresponding chemical reaction ODE models, chemical Langevin equation SDE models, and stochastic chemical kinetics jump process models. As a simple example, the code below creates a SIR model, and solves the corresponding ODE, SDE and jump process models.
+A `ReactionSystem` represents a system of chemical reactions. Conversions are provided to generate corresponding chemical reaction ODE models, chemical Langevin equation SDE models, and stochastic chemical kinetics jump process models. As a simple example, the code below creates a SIR model, and solves the corresponding ODE, SDE, and jump process models.
 
 ```julia
 using ModelingToolkit, OrdinaryDiffEq, StochasticDiffEq, DiffEqJump
@@ -56,4 +56,4 @@ ismassaction
 
 ```@docs
 Base.convert
-```
+```

src/build_function.jl

@@ -14,10 +14,10 @@ struct DistributedForm <: ParallelForm end
 
 Generates a numerically-usable function from a ModelingToolkit `Expression`.
 If the `Expression` is an `Operation`, the generated function is a function
-with a scalar output, otherwise if it's an `AbstractArray{Operation}` the output
+with a scalar output, otherwise if it's an `AbstractArray{Operation}`, the output
 is two functions, one for out-of-place AbstractArray output and a second which
 is a mutating function. The outputted functions match the given argument order,
-i.e. f(u,p,args...) for the out-of-place and scalar functions and
+i.e., f(u,p,args...) for the out-of-place and scalar functions and
 `f!(du,u,p,args..)` for the in-place version.
 
 ```julia
@@ -38,7 +38,7 @@ Arguments:
 - `expression`: Whether to generate code or whether to generate the compiled form.
   By default, `expression = Val{true}`, which means that the code for the
   function is returned. If `Val{false}`, then the returned value is a compiled
-  Julia function which utilizes GeneralizedGenerated.jl in order to world-age
+  Julia function, which utilizes GeneralizedGenerated.jl in order to world-age
   free.
 
 Keyword Arguments:

src/differentials.jl

@@ -76,7 +76,7 @@ julia> ModelingToolkit.derivative(sin(x), 1)
 cos(x())
 ```
 
-Note that the function does not recurse into the operation's arguments, i.e. the
+Note that the function does not recurse into the operation's arguments, i.e., the
 chain rule is not applied:
 
 ```jldoctest label1

src/equations.jl

@@ -7,9 +7,9 @@ An equality relationship between two expressions.
 $(FIELDS)
 """
 struct Equation
-    """The expression on the left hand side of the equation."""
+    """The expression on the left-hand side of the equation."""
     lhs::Expression
-    """The expression on the right hand side of the equation."""
+    """The expression on the right-hand side of the equation."""
     rhs::Expression
 end
 Base.:(==)(a::Equation, b::Equation) = isequal((a.lhs, a.rhs), (b.lhs, b.rhs))

src/function_registration.jl

@@ -2,7 +2,7 @@
 """
 $(SIGNATURES)
 
-Registers a function call as a primative for the `Operation` graph of the
+Registers a function call as a primitive for the `Operation` graph of the
 ModelingToolkit IR. Example:
 
 ```julia

src/latexify_recipes.jl

@@ -3,7 +3,7 @@
     env --> :align
     cdot --> false
 
-    # Convert both the left and right hand side to expressions of basic types
+    # Convert both the left- and right-hand sides to expressions of basic types
     # that latexify can deal with.
 
     rhs = getfield.(eqs, :rhs)

src/operations.jl

@@ -55,7 +55,7 @@ Base.isequal(::Operation, ::Constant ) = false
 Base.isequal(::Constant , ::Operation) = false
 
 # provide iszero for Operations to help sparse addition and multiplication
-# e.g. we want to tell the sparse library that iszero(zero(Operation) + zero(Operation)) == true
+# e.g., we want to tell the sparse library that iszero(zero(Operation) + zero(Operation)) == true
 Base.iszero(x::Operation) = (_x = simplify(x); _x isa Constant && iszero(_x.value))
 
 Base.show(io::IO, O::Operation) = print(io, convert(Expr, O))

src/variables.jl

@@ -25,9 +25,9 @@ as equal.
 $(FIELDS)
 
 For example, the following code defines an independent variable `t`, a parameter
-`α`, a function parameter `σ`, a variable `x` which depends on `t`, a variable
-`y` with no dependents, a variable `z` which depends on `t`, `α`, and `x(t)`
-and a parameters `β₁` and `β₂`.
+`α`, a function parameter `σ`, a variable `x`, which depends on `t`, a variable
+`y` with no dependents, a variable `z`, which depends on `t`, `α`, and `x(t)`
+and parameters `β₁` and `β₂`.
 
 
 ```julia