Merge pull request #2019 from ArnoStrouwen/LT

[skip ci] LanguageTool

Author: ChrisRackauckas

docs/src/basics/FAQ.md

@@ -46,10 +46,10 @@ such as `@register_symbolic`, are described in detail
 
 ## Using ModelingToolkit with Optimization / Automatic Differentiation
 
-If you are using ModelingToolkit inside of a loss function and are having issues with
+If you are using ModelingToolkit inside a loss function and are having issues with
 mixing MTK with automatic differentiation, getting performance, etc... don't! Instead, use
-MTK outside of the loss function to generate the code, and then use the generated code
-inside of the loss function.
+MTK outside the loss function to generate the code, and then use the generated code
+inside the loss function.
 
 For example, let's say you were building ODEProblems in the loss function like:
 
@@ -62,9 +62,9 @@ end
 ```
 
 Since `ODEProblem` on a MTK `sys` will have to generate code, this will be slower than
-caching the generated code, and will required automatic differentiation to go through the
+caching the generated code, and will require automatic differentiation to go through the
 code generation process itself. All of this is unnecessary. Instead, generate the problem
-once outside of the loss function, and remake the prob inside of the loss function:
+once outside the loss function, and remake the prob inside of the loss function:
 
 ```julia
 prob = ODEProblem(sys, [], [p1 => p[1], p2 => p[2]])

docs/src/comparison.md

@@ -7,11 +7,11 @@
   [Dymola](https://www.3ds.com/products-services/catia/products/dymola/) and
   [OpenModelica](https://openmodelica.org/), which have differing levels of
   performance and can give different results on the same model. Many of the
-  commonly used Modelica compilers are not open source. ModelingToolkit.jl
-  is a language with a single canonical open source implementation.
+  commonly used Modelica compilers are not open-source. ModelingToolkit.jl
+  is a language with a single canonical open-source implementation.
 - All current Modelica compiler implementations are fixed and not extendable
   by the users from the Modelica language itself. For example, the Dymola
-  compiler [shares its symbolic processing pipeline](https://www.claytex.com/tech-blog/model-translation-and-symbolic-manipulation/)
+  compiler [shares its symbolic processing pipeline](https://www.claytex.com/tech-blog/model-translation-and-symbolic-manipulation/),
   which is roughly equivalent to the `dae_index_lowering` and `structural_simplify`
   of ModelingToolkit.jl. ModelingToolkit.jl is an open and hackable transformation
   system which allows users to add new non-standard transformations and control
@@ -34,23 +34,23 @@
   academic reviews such as [this one](https://arxiv.org/abs/1909.00484). In this
   sense, ModelingToolkit.jl is more similar to the Simscape sub-environment.
 - Simulink is used from MATLAB while ModelingToolkit.jl is used from Julia.
-  Thus any user defined functions have the performance of their host language.
+  Thus any user-defined functions have the performance of their host language.
   For information on the performance differences between Julia and MATLAB,
-  consult [open benchmarks](https://julialang.org/benchmarks/) which demonstrate
+  consult [open benchmarks](https://julialang.org/benchmarks/), which demonstrate
   Julia as an order of magnitude or more faster in many cases due to its JIT
   compilation.
-- Simulink uses the MATLAB differential equation solvers while ModelingToolkit.jl
+- Simulink uses the MATLAB differential equation solvers, while ModelingToolkit.jl
   uses [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/). For a systematic
   comparison between the solvers, consult
-  [open benchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/)
+  [open benchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/),
   which demonstrate two orders of magnitude performance advantage for the native
   Julia solvers across many benchmark problems.
 - Simulink comes with a Graphical User Interface (GUI), ModelingToolkit.jl
   does not.
 - Simulink is a proprietary software, meaning users cannot actively modify or
   extend the software. ModelingToolkit.jl is built in Julia and used in Julia,
   where users can actively extend and modify the software interactively in the
-  REPL and contribute to its open source repositories.
+  REPL and contribute to its open-source repositories.
 - Simulink covers ODE and DAE systems. ModelingToolkit.jl has a much more
   expansive set of system types, including SDEs, PDEs, optimization problems,
   and more.
@@ -72,9 +72,9 @@
   In addition, the DifferentialEquations.jl interface is confederated, meaning
   that any user can dynamically extend the system to add new solvers to the
   interface by defining new dispatches of solve.
-- CASADI's DAEBuilder does not implement efficiency transformations like tearing
+- CASADI's DAEBuilder does not implement efficiency transformations like tearing,
   which are standard in the ModelingToolkit.jl transformation pipeline.
-- CASADI supports special functionality for quadratic programming problems while
+- CASADI supports special functionality for quadratic programming problems, while
   ModelingToolkit only provides nonlinear programming via `OptimizationSystem`.
 - ModelingToolkit.jl integrates with its host language Julia, so Julia code
   can be automatically converted into ModelingToolkit expressions. Users of

docs/src/examples/higher_order.md

@@ -5,7 +5,7 @@ systems. These transformations allow for symbolically changing
 the representation of the model to problems that are easier to
 numerically solve. One simple to demonstrate transformation is the
 `structural_simplify` with does a lot of tricks, one being the
-transformation that sends an Nth order ODE
+transformation that sends a Nth order ODE
 to a 1st order ODE.
 
 To see this, let's define a second order riff on the Lorenz equations.

docs/src/examples/modelingtoolkitize_index_reduction.md

@@ -1,7 +1,7 @@
 # Automated Index Reduction of DAEs
 
 In many cases one may accidentally write down a DAE that is not easily solvable
-by numerical methods. In this tutorial we will walk through an example of a
+by numerical methods. In this tutorial, we will walk through an example of a
 pendulum which accidentally generates an index-3 DAE, and show how to use the
 `modelingtoolkitize` to correct the model definition before solving.
 
@@ -39,7 +39,7 @@ plot(sol, idxs=states(traced_sys))
 
 ### Attempting to Solve the Equation
 
-In this tutorial we will look at the pendulum system:
+In this tutorial, we will look at the pendulum system:
 
 ```math
 \begin{aligned}
@@ -88,21 +88,21 @@ Did you implement the DAE incorrectly? No. Is the solver broken? No.
 It turns out that this is a property of the DAE that we are attempting to solve.
 This kind of DAE is known as an index-3 DAE. For a complete discussion of DAE
 index, see [this article](http://www.scholarpedia.org/article/Differential-algebraic_equations).
-Essentially the issue here is that we have 4 differential variables (``x``, ``v_x``, ``y``, ``v_y``)
+Essentially, the issue here is that we have 4 differential variables (``x``, ``v_x``, ``y``, ``v_y``)
 and one algebraic variable ``T`` (which we can know because there is no `D(T)`
 term in the equations). An index-1 DAE always satisfies that the Jacobian of
 the algebraic equations is non-singular. Here, the first 4 equations are
 differential equations, with the last term the algebraic relationship. However,
 the partial derivative of `x^2 + y^2 - L^2` w.r.t. `T` is zero, and thus the
-Jacobian of the algebraic equations is the zero matrix and thus it's singular.
-This is a very quick way to see whether the DAE is index 1!
+Jacobian of the algebraic equations is the zero matrix, and thus it's singular.
+This is a rapid way to see whether the DAE is index 1!
 
 The problem with higher order DAEs is that the matrices used in Newton solves
 are singular or close to singular when applied to such problems. Because of this
 fact, the nonlinear solvers (or Rosenbrock methods) break down, making them
 difficult to solve. The classic paper [DAEs are not ODEs](https://epubs.siam.org/doi/10.1137/0903023)
 goes into detail on this and shows that many methods are no longer convergent
-when index is higher than one. So it's not necessarily the fault of the solver
+when index is higher than one. So, it's not necessarily the fault of the solver
 or the implementation: this is known.
 
 But that's not a satisfying answer, so what do you do about it?
@@ -125,7 +125,7 @@ v_y^\prime =& y T - g \\
 
 Note that this is mathematically-equivalent to the equation that we had before,
 but the Jacobian w.r.t. `T` of the algebraic equation is no longer zero because
-of the substitution. This means that if you wrote down this version of the model
+of the substitution. This means that if you wrote down this version of the model,
 it will be index-1 and solve correctly! In fact, this is how DAE index is
 commonly defined: the number of differentiations it takes to transform the DAE
 into an ODE, where an ODE is an index-0 DAE by substituting out all of the
@@ -154,12 +154,12 @@ plot(sol, idxs=states(traced_sys))
 ```
 
 Note that plotting using `states(traced_sys)` is done so that any
-variables which are symbolically eliminated, or any variable reorderings
+variables which are symbolically eliminated, or any variable reordering
 done for enhanced parallelism/performance, still show up in the resulting
 plot and the plot is shown in the same order as the original numerical
 code.
 
-Note that we can even go a little bit further. If we use the `ODAEProblem`
+Note that we can even go a bit further. If we use the `ODAEProblem`
 constructor, we can remove the algebraic equations from the states of the
 system and fully transform the index-3 DAE into an index-0 ODE which can
 be solved via an explicit Runge-Kutta method:

docs/src/examples/perturbation.md

@@ -36,7 +36,7 @@ end
 
 In the first two examples, we applied the perturbation method to algebraic problems. However, the main power of the perturbation method is to solve differential equations (usually ODEs, but also occasionally PDEs). Surprisingly, the main procedure developed to solve algebraic problems works well for differential equations. In fact, we will use the same two helper functions, `collect_powers` and `solve_coef`. The main difference is in the way we expand the dependent variables. For algebraic problems, the coefficients of $\epsilon$ are constants; whereas, for differential equations, they are functions of the dependent variable (usually time).
 
-As the first ODE example, we have chosen a simple and well-behaved problem, which is a variation of a standard first-year physics problem: what is the trajectory of an object (say, a ball or a rocket) thrown vertically at velocity $v$ from the surface of a planet? Assuming a constant acceleration of gravity, $g$, every burgeoning physicist knows the answer: $x(t) = x(0) + vt - \frac{1}{2}gt^2$. However, what happens if $g$ is not constant? Specifically, $g$ is inversely proportional to the distant from the center of the planet. If $v$ is large and the projectile travels a large fraction of the radius of the planet, the assumption of constant gravity does not hold anymore. However, unless $v$ is large compared to the escape velocity, the correction is usually small. After simplifications and change of variables to dimensionless, the problem becomes
+As the first ODE example, we have chosen a simple and well-behaved problem, which is a variation of a standard first-year physics problem: what is the trajectory of an object (say, a ball, or a rocket) thrown vertically at velocity $v$ from the surface of a planet? Assuming a constant acceleration of gravity, $g$, every burgeoning physicist knows the answer: $x(t) = x(0) + vt - \frac{1}{2}gt^2$. However, what happens if $g$ is not constant? Specifically, $g$ is inversely proportional to the distant from the center of the planet. If $v$ is large and the projectile travels a large fraction of the radius of the planet, the assumption of constant gravity does not hold anymore. However, unless $v$ is large compared to the escape velocity, the correction is usually small. After simplifications and change of variables to dimensionless, the problem becomes
 
 ```math
   \ddot{x}(t) = -\frac{1}{(1 + \epsilon x(t))^2}
@@ -87,7 +87,7 @@ subs = Dict(∂∂y[i] => D(D(y[i])) for i in eachindex(y))
 eqs = [substitute(first(v), subs) ~ substitute(last(v), subs) for v in vals]
 ```
 
-We are nearly there! From this point on, the rest is standard ODE solving procedures. Potentially we can use a symbolic ODE solver to find a closed form solution to this problem. However, **Symbolics.jl** currently does not support this functionality. Instead, we solve the problem numerically. We form an `ODESystem`, lower the order (convert second derivatives to first), generate an `ODEProblem` (after passing the correct initial conditions), and, finally, solve it.
+We are nearly there! From this point on, the rest is standard ODE solving procedures. Potentially, we can use a symbolic ODE solver to find a closed form solution to this problem. However, **Symbolics.jl** currently does not support this functionality. Instead, we solve the problem numerically. We form an `ODESystem`, lower the order (convert second derivatives to first), generate an `ODEProblem` (after passing the correct initial conditions), and, finally, solve it.
 
 ```julia
 using ModelingToolkit, DifferentialEquations

docs/src/examples/sparse_jacobians.md

@@ -1,13 +1,13 @@
 # Automated Sparse Analytical Jacobians
 
 In many cases where you have large stiff differential equations, getting a
-sparse Jacobian can be essential for performance. In this tutorial we will show
+sparse Jacobian can be essential for performance. In this tutorial, we will show
 how to use `modelingtoolkitize` to regenerate an `ODEProblem` code with
 the analytical solution to the sparse Jacobian, along with the sparsity
 pattern required by DifferentialEquations.jl's solvers to specialize the solving
 process.
 
-First let's start out with an implementation of the 2-dimensional Brusselator
+First, let's start out with an implementation of the 2-dimensional Brusselator
 partial differential equation discretized using finite differences:
 
 ```@example sparsejac

docs/src/examples/spring_mass.md

@@ -1,6 +1,6 @@
-# Component-Based Modeling a Spring-Mass System
+# Component-Based Modeling of a Spring-Mass System
 
-In this tutorial we will build a simple component-based model of a spring-mass system. A spring-mass system consists of one or more masses connected by springs. [Hooke's law](https://en.wikipedia.org/wiki/Hooke%27s_law) gives the force exerted by a spring when it is extended or compressed by a given distance. This specifies a differential-equation system where the acceleration of the masses is specified using the forces acting on them.
+In this tutorial, we will build a simple component-based model of a spring-mass system. A spring-mass system consists of one or more masses connected by springs. [Hooke's law](https://en.wikipedia.org/wiki/Hooke%27s_law) gives the force exerted by a spring when it is extended or compressed by a given distance. This specifies a differential-equation system where the acceleration of the masses is specified using the forces acting on them.
 
 ## Copy-Paste Example
 
@@ -58,7 +58,7 @@ plot(sol)
 
 ## Explanation
 ### Building the components
-For each component we use a Julia function that returns an `ODESystem`. At the top, we define the fundamental properties of a `Mass`: it has a mass `m`, a position `pos` and a velocity `v`. We also define that the velocity is the rate of change of position with respect to time.
+For each component, we use a Julia function that returns an `ODESystem`. At the top, we define the fundamental properties of a `Mass`: it has a mass `m`, a position `pos` and a velocity `v`. We also define that the velocity is the rate of change of position with respect to time.
 
 ```@example component
 function Mass(; name, m = 1.0, xy = [0., 0.], u = [0., 0.])
@@ -69,7 +69,7 @@ function Mass(; name, m = 1.0, xy = [0., 0.], u = [0., 0.])
 end
 ```
 
-Note that this is an incompletely specified `ODESystem`. It cannot be simulated on its own since the equations for the velocity `v[1:2](t)` are unknown. Notice the addition of a `name` keyword. This allows us to generate different masses with different names. A `Mass` can now be constructed as:
+Note that this is an incompletely specified `ODESystem`. It cannot be simulated on its own, since the equations for the velocity `v[1:2](t)` are unknown. Notice the addition of a `name` keyword. This allows us to generate different masses with different names. A `Mass` can now be constructed as:
 
 ```@example component
 Mass(name = :mass1)
@@ -81,7 +81,7 @@ Or using the `@named` helper macro
 @named mass1 = Mass()
 ```
 
-Next we build the spring component. It is characterised by the spring constant `k` and the length `l` of the spring when no force is applied to it. The state of a spring is defined by its current length and direction.
+Next, we build the spring component. It is characterized by the spring constant `k` and the length `l` of the spring when no force is applied to it. The state of a spring is defined by its current length and direction.
 
 ```@example component
 function Spring(; name, k = 1e4, l = 1.)

docs/src/examples/tearing_parallelism.md

@@ -1,6 +1,6 @@
 # Exposing More Parallelism By Tearing Algebraic Equations in ODESystems
 
-Sometimes it can be very non-trivial to parallelize a system. In this tutorial
+Sometimes it can be very non-trivial to parallelize a system. In this tutorial,
 we will demonstrate how to make use of `structural_simplify` to expose more
 parallelism in the solution process and parallelize the resulting simulation.
 
@@ -150,8 +150,8 @@ If you look at the system we defined:
 length(equations(big_rc))
 ```
 
-You see it started as a massive 1051 set of equations. However, after eliminating
-redundancies we arrive at 151 equations:
+You see, it started as a massive 1051 set of equations. However, after eliminating
+redundancies, we arrive at 151 equations:
 
 ```@example tearing
 equations(sys)
@@ -178,7 +178,7 @@ equations, and so the full set of equations must be solved together. That expose
 no parallelism. However, the Block Lower Triangular (BLT) transformation exposes
 independent blocks. This is then further improved by the tearing process, which
 removes 90% of the equations and transforms the nonlinear equations into 50
-independent blocks *which can now all be solved in parallel*. The conclusion
+independent blocks, *which can now all be solved in parallel*. The conclusion
 is that, your attempts to parallelize are neigh: performing parallelism after
 structural simplification greatly improves the problem that can be parallelized,
 so this is better than trying to do it by hand.