update HISTORY and README for v15

Author: isaacsas

HISTORY.md

@@ -9,22 +9,8 @@
   (at the time the release is made). If you need a dependency version increased,
   please open an issue and we can update it and make a new Catalyst release once
   testing against the newer dependency version is complete.
-- It is no longer recommended to install and use the full OrdinaryDiffEq library
-  to access specific ODE solvers. Instead, only install the specific
-  OrdinaryDiffEq sub-libraries that contain the desired solver. This
-  significantly reduces installation and package loading times. I.e. to use the
-  default solver that auto-switches between explicit and implicit methods,
-  install `OrdinaryDiffEqDefault`. To use `Tsit5` install `OrdinaryDiffEqTsit5`,
-  etc. The possible sub-libraries, each containing different solvers, can be
-  viewed [here](https://github.com/SciML/OrdinaryDiffEq.jl/tree/master/lib).
-- It should now be safe to use `remake` on problems which have had conservation
-  laws removed with the exception of `NonlinearProblem`s or `NonlinearSystem`s.
-  For NonlinearProblems it is safe to use `remake` if only updating `u0` values,
-  but it is not safe to update the value of the conserved constant, `Γ`. See
-  [the FAQ](https://docs.sciml.ai/Catalyst/stable/faqs/#faq_remake_nonlinprob)
-  for details.
-- New formula for inferring variables from equations (declared using the
-  `@equations` options) in the DSL. The order of inference of
+- **BREAKING:** New formula for inferring variables from equations (declared
+  using the `@equations` options) in the DSL. The order of inference of
   species/variables/parameters is now:
     1. Every symbol explicitly declared using `@species`, `@variables`, and
        `@parameters` are assigned to the correct category.
@@ -45,10 +31,10 @@
        and `@differentials` options still hold. Finally, the `@require_declaration`
        options (described in more detail below) can now be used to require everything
        to be explicitly declared.
-- New formula for determining whether the default differentials have been used
-  within an `@equations` option. Now, if any expression `D(...)` is encountered
-  (where `...` can be anything), this is inferred as usage of the default
-  differential D. E.g. in the following equations `D` is inferred as a
+- **BREAKING:** New formula for determining whether the default differentials
+  have been used within an `@equations` option. Now, if any expression `D(...)`
+  is encountered (where `...` can be anything), this is inferred as usage of the
+  default differential D. E.g. in the following equations `D` is inferred as a
   differential with respect to the default independent variable:
   ```julia
   @reaction_network begin
@@ -61,10 +47,10 @@
   Please note that this cannot be used at the same time as `D` is used to
   represent a species, variable, or parameter (including if these are implicitly
   designated as such by e.g. appearing as a reaction reactant). 
-- Array symbolics support is more consistent with ModelingToolkit v9. Parameter
-  arrays are no longer scalarized by Catalyst, while species and variables
-  arrays still are (as in ModelingToolkit). As such, parameter arrays should now
-  be specified as arrays in value mappings, i.e.
+- **BREAKING:** Array symbolics support is more consistent with ModelingToolkit
+  v9. Parameter arrays are no longer scalarized by Catalyst, while species and
+  variables arrays still are (as in ModelingToolkit). As such, parameter arrays
+  should now be specified as arrays in value mappings, i.e.
   ```julia
   @parameters k[1:4]
   pmap = [k => rand(4)]
@@ -73,47 +59,27 @@
   *not* to do this as it has signifcant performance costs with ModelingToolkit
   v9. Note, scalarized parameter arrays passed to the two-argument
   `ReactionSystem` constructor may become unscalarized.
-- Functional (e.g. time-dependent) parameters can now be used in Catalyst
-  models. These can e.g. be used to incorporate arbitrary time-dependent
-  functions (as a parameter) in a model. For more details on how to use these,
-  please read:
-  https://docs.sciml.ai/Catalyst/stable/model_creation/functional_parameters/.
-- We have introduced a restriction on bundling of reactions in the DSL. Now,
-  bundling is not permitted if multiple rates are provided but only one set each
-  of substrates/products. E.g. this model:
+- **BREAKING:** We have introduced a restriction on bundling of reactions in the
+  DSL. Now, bundling is not permitted if multiple rates are provided but only
+  one set each of substrates/products. E.g. this model:
   ```julia
   @reaction_network begin
     (k1,k2), X --> Y
   end
   ```
-  will now throw an error. The reason that users attempting to write bi-directional 
-  reactions but typing `-->` instead of `<-->` would get a wrong model. We decided that
-  this kind of bundling was unlikely to be used, and throwing errors for people who
-  made the typo was more important. 
-
-  If you use this type of bundling and it indeed is useful to you, please raise and issue
+  will now throw an error. The reason that users attempting to write
+  bi-directional reactions but typing `-->` instead of `<-->` would get a wrong
+  model. We decided that this kind of bundling was unlikely to be used, and
+  throwing errors for people who made the typo was more important. If you use
+  this type of bundling and it indeed is useful to you, please raise and issue
   and we will see if we can sort something out.
-- Scoped species/variables/parameters are now treated similar to the latest MTK
-  releases (≥ 9.49).
-- A tutorial on making interactive plot displays using Makie has been added.
-- The BifurcationKit extension has been updated to v.4.
-- There is a new DSL option `@require_declaration` that will turn off automatic inferring for species, parameters, and variables in the DSL. For example, the following will now error:
-  ```julia
-  rn = @reaction_network begin
-    @require_declaration
-    (k1, k2), A <--> B
-  end
-  ```
-  When this flag is set, all symbolics must be explicitly declared. 
-  ```julia
-  rn = @reaction_network begin
-    @species A(t) B(t)
-    @parameters k1 k2
-    @require_declaration
-    (k1, k2), A <--> B
-  end
-  ```
-- Catalyst's network visualization capability has shifted from using Graphviz to [GraphMakie.jl](https://graph.makie.org/stable/). To use this functionality, load the GraphMakie extension by installing `Catalyst` and `GraphMakie`, along with a Makie backend like `GLMakie`. There are two new methods for visualizing graphs: `plot_network` and `plot_complexes`, which respectively display the species-reaction graph and complex graph.
+- **BREAKING:** Catalyst's network visualization capability has shifted from
+  using Graphviz to [GraphMakie.jl](https://graph.makie.org/stable/). To use
+  this functionality, load the GraphMakie extension by installing `Catalyst` and
+  `GraphMakie`, along with a Makie backend like `CairoMakie` or `GLMakie`. There
+  are two new methods for visualizing graphs: `plot_network` and
+  `plot_complexes`, which respectively display the species-reaction graph and
+  complex graph.
   ```julia
   using Catalyst, GraphMakie, GLMakie
   brusselator = @reaction_network begin
@@ -124,13 +90,15 @@
   end
   plot_network(brusselator)
   ```
-- The letter Ø (used in Danish/Norwegian alphabet) is now considered the same as ∅ (empty set). It can no longer be used as a species/parameter.
-- When converting a Catalyst `ReactionSystem` to a ModelingToolkit system, for
-  example an `ODESystem`, Catalyst defined functions like `hill(A,B,C,D)` are
-  now replaced with the explicit rational function they represent in the
-  equations of the generated system. For example `mm(X,v,K)` will be replaced
-  with `v*X / (X + K)`. This can be disabled by passing the keyword argument
-  `expand_catalyst_funs = false`. e.g.
+- **BREAKING:** The letter Ø (used in Danish/Norwegian alphabet) is now
+  considered the same as ∅ (empty set). It can no longer be used as a
+  species/parameter.
+- **BREAKING:** When converting a Catalyst `ReactionSystem` to a ModelingToolkit
+  system, for example an `ODESystem`, Catalyst defined functions like
+  `hill(A,B,C,D)` are now replaced with the explicit rational function they
+  represent in the equations of the generated system. For example `mm(X,v,K)`
+  will be replaced with `v*X / (X + K)`. This can be disabled by passing the
+  keyword argument `expand_catalyst_funs = false`. e.g.
   ```julia
   using Catalyst
   rn = @reaction_network begin
@@ -145,6 +113,47 @@
   generates an ODE system with `D(A) ~ -A(t)*hill(X, v, K, n)`. This keyword
   argument can also be passed to problems defined over `ReactionSystem`s, i.e.
   when calling `ODEProblem(rn, u0, tspan, p; expand_catalyst_funs = false)`.
+- It is no longer recommended to install and use the full OrdinaryDiffEq library
+  to access specific ODE solvers. Instead, only install the specific
+  OrdinaryDiffEq sub-libraries that contain the desired solver. This
+  significantly reduces installation and package loading times. I.e. to use the
+  default solver that auto-switches between explicit and implicit methods,
+  install `OrdinaryDiffEqDefault`. To use `Tsit5` install `OrdinaryDiffEqTsit5`,
+  etc. The possible sub-libraries, each containing different solvers, can be
+  viewed [here](https://github.com/SciML/OrdinaryDiffEq.jl/tree/master/lib).
+- It should now be safe to use `remake` on problems which have had conservation
+  laws removed with the exception of `NonlinearProblem`s or `NonlinearSystem`s.
+  For NonlinearProblems it is safe to use `remake` if only updating `u0` values,
+  but it is not safe to update the value of the conserved constant, `Γ`. See
+  [the FAQ](https://docs.sciml.ai/Catalyst/stable/faqs/#faq_remake_nonlinprob)
+  for details.
+- Functional (e.g. time-dependent) parameters can now be used in Catalyst
+  models. These can e.g. be used to incorporate arbitrary time-dependent
+  functions (as a parameter) in a model. For more details on how to use these,
+  please read:
+  https://docs.sciml.ai/Catalyst/stable/model_creation/functional_parameters/.
+- Scoped species/variables/parameters are now treated similar to the latest MTK
+  releases (≥ 9.49).
+- A tutorial on making interactive plot displays using Makie has been added.
+- The BifurcationKit extension has been updated to v.4.
+- There is a new DSL option `@require_declaration` that will turn off automatic
+  inferring for species, parameters, and variables in the DSL. For example, the
+  following will now error:
+  ```julia
+  rn = @reaction_network begin
+    @require_declaration
+    (k1, k2), A <--> B
+  end
+  ```
+  When this flag is set, all symbolics must be explicitly declared. 
+  ```julia
+  rn = @reaction_network begin
+    @species A(t) B(t)
+    @parameters k1 k2
+    @require_declaration
+    (k1, k2), A <--> B
+  end
+  ```
 
 ## Catalyst 14.4.1
 - Support for user-defined functions on the RHS when providing coupled equations 

README.md

@@ -47,9 +47,10 @@ Pkg.add("Catalyst")
 
 ## Breaking changes and new features
 
-**NOTE:** Version 14 is a breaking release, prompted by the release of ModelingToolkit.jl version 9. This caused several breaking changes in how Catalyst models are represented and interfaced with.
-
-Breaking changes and new functionality are summarized in the [HISTORY.md](HISTORY.md) file. Furthermore, a migration guide on how to adapt your workflows to the new v14 update can be found [here](https://docs.sciml.ai/Catalyst/stable/v14_migration_guide/).
+**NOTE:** Version 15 is a breaking release, though most breaking changes are
+likely to only impact libraries being developed on top of Catalyst. Please
+see the [HISTORY.md](HISTORY.md) file for a summary of breaking changes and new
+functionality. 
 
 ## Tutorials and documentation