|
1 | 1 | # Breaking updates and feature summaries across releases |
2 | 2 |
|
3 | 3 | ## Catalyst unreleased (master branch) |
| 4 | + |
| 5 | +## Catalyst 15.0 |
4 | 6 | - The Catalyst release process is changing; certain core dependencies of |
5 | 7 | Catalyst will now be capped to ensure Catalyst releases are only installed |
6 | 8 | with versions of dependencies for which Catalyst CI and doc build tests pass |
7 | 9 | (at the time the release is made). If you need a dependency version increased, |
8 | 10 | please open an issue and we can update it and make a new Catalyst release once |
9 | 11 | testing against the newer dependency version is complete. |
10 | | -- It is no longer recommended to install and use the full OrdinaryDiffEq library to access specific ODE solvers. |
11 | | - Instead, only install the specific OrdinaryDiffEq sub-libraries that contain the desired |
12 | | - solver. This significantly reduces installation and package loading times. I.e. to use the default |
13 | | - solver that auto-switches between explicit and implicit methods, install `OrdinaryDiffEqDefault`. To |
14 | | - use `Tsit5` install `OrdinaryDiffEqTsit5`, etc. The possible sub-libraries, each containing different solvers, |
15 | | - can be viewed [here](https://github.com/SciML/OrdinaryDiffEq.jl/tree/master/lib). |
16 | | -- 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: |
17 | | - (1) Every symbol explicitly declared using `@species`, `@variables`, and `@parameters` are assigned to the correct category. |
18 | | - (2) Every symbol used as a reaction reactant is inferred as a species. |
19 | | - (3) Every symbol not declared in (1) or (2) that occurs in an expression provided after `@equations` is inferred as a variable. |
20 | | - (4) Every symbol not declared in (1), (2), or (3) that occurs either as a reaction rate or stoichiometric coefficient is inferred to be a parameter. |
21 | | - E.g. in |
22 | | - ```julia |
23 | | - @reaction_network begin |
24 | | - @equations V1 + S ~ V2^2 |
25 | | - (p + S + V1), S --> 0 |
26 | | - end |
27 | | - ``` |
28 | | - `S` is inferred as a species, `V1` and `V2` as variables, and `p` as a parameter. The previous special cases for the `@observables`, `@compounds`, 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. |
29 | | -- 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: |
| 12 | +- **BREAKING:** New formula for inferring variables from equations (declared |
| 13 | + using the `@equations` options) in the DSL. The order of inference of |
| 14 | + species/variables/parameters is now: |
| 15 | + 1. Every symbol explicitly declared using `@species`, `@variables`, and |
| 16 | + `@parameters` are assigned to the correct category. |
| 17 | + 2. Every symbol used as a reaction reactant is inferred as a species. |
| 18 | + 3. Every symbol not declared in (1) or (2) that occurs in an expression |
| 19 | + provided after `@equations` is inferred as a variable. |
| 20 | + 4. Every symbol not declared in (1), (2), or (3) that occurs either as a |
| 21 | + reaction rate or stoichiometric coefficient is inferred to be a |
| 22 | + parameter. E.g. in |
| 23 | + ```julia |
| 24 | + @reaction_network begin |
| 25 | + @equations V1 + S ~ V2^2 |
| 26 | + (p + S + V1), S --> 0 |
| 27 | + end |
| 28 | + ``` |
| 29 | + `S` is inferred as a species, `V1` and `V2` as variables, and `p` as a |
| 30 | + parameter. The previous special cases for the `@observables`, `@compounds`, |
| 31 | + and `@differentials` options still hold. Finally, the `@require_declaration` |
| 32 | + options (described in more detail below) can now be used to require everything |
| 33 | + to be explicitly declared. |
| 34 | +- **BREAKING:** New formula for determining whether the default differentials |
| 35 | + have been used within an `@equations` option. Now, if any expression `D(...)` |
| 36 | + is encountered (where `...` can be anything), this is inferred as usage of the |
| 37 | + default differential D. E.g. in the following equations `D` is inferred as a |
| 38 | + differential with respect to the default independent variable: |
30 | 39 | ```julia |
31 | 40 | @reaction_network begin |
32 | 41 | @equations D(V) + V ~ 1 |
|
35 | 44 | @equations D(D(V)) ~ 1 |
36 | 45 | end |
37 | 46 | ``` |
38 | | - 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). |
39 | | -- Array symbolics support is more consistent with ModelingToolkit v9. Parameter |
40 | | - arrays are no longer scalarized by Catalyst, while species and variables |
41 | | - arrays still are (as in ModelingToolkit). As such, parameter arrays should now |
42 | | - be specified as arrays in value mappings, i.e. |
| 47 | + Please note that this cannot be used at the same time as `D` is used to |
| 48 | + represent a species, variable, or parameter (including if these are implicitly |
| 49 | + designated as such by e.g. appearing as a reaction reactant). |
| 50 | +- **BREAKING:** Array symbolics support is more consistent with ModelingToolkit |
| 51 | + v9. Parameter arrays are no longer scalarized by Catalyst, while species and |
| 52 | + variables arrays still are (as in ModelingToolkit). As such, parameter arrays |
| 53 | + should now be specified as arrays in value mappings, i.e. |
43 | 54 | ```julia |
44 | 55 | @parameters k[1:4] |
45 | 56 | pmap = [k => rand(4)] |
|
48 | 59 | *not* to do this as it has signifcant performance costs with ModelingToolkit |
49 | 60 | v9. Note, scalarized parameter arrays passed to the two-argument |
50 | 61 | `ReactionSystem` constructor may become unscalarized. |
| 62 | +- **BREAKING:** We have introduced a restriction on bundling of reactions in the |
| 63 | + DSL. Now, bundling is not permitted if multiple rates are provided but only |
| 64 | + one set each of substrates/products. E.g. this model: |
| 65 | + ```julia |
| 66 | + @reaction_network begin |
| 67 | + (k1,k2), X --> Y |
| 68 | + end |
| 69 | + ``` |
| 70 | + will now throw an error. The reason that users attempting to write |
| 71 | + bi-directional reactions but typing `-->` instead of `<-->` would get a wrong |
| 72 | + model. We decided that this kind of bundling was unlikely to be used, and |
| 73 | + throwing errors for people who made the typo was more important. If you use |
| 74 | + this type of bundling and it indeed is useful to you, please raise and issue |
| 75 | + and we will see if we can sort something out. |
| 76 | +- **BREAKING:** Catalyst's network visualization capability has shifted from |
| 77 | + using Graphviz to [GraphMakie.jl](https://graph.makie.org/stable/). To use |
| 78 | + this functionality, load the GraphMakie extension by installing `Catalyst` and |
| 79 | + `GraphMakie`, along with a Makie backend like `CairoMakie` or `GLMakie`. There |
| 80 | + are two new methods for visualizing graphs: `plot_network` and |
| 81 | + `plot_complexes`, which respectively display the species-reaction graph and |
| 82 | + complex graph. |
| 83 | + ```julia |
| 84 | + using Catalyst, GraphMakie, GLMakie |
| 85 | + brusselator = @reaction_network begin |
| 86 | + A, ∅ --> X |
| 87 | + 1, 2X + Y --> 3X |
| 88 | + B, X --> Y |
| 89 | + 1, X --> ∅ |
| 90 | + end |
| 91 | + plot_network(brusselator) |
| 92 | + ``` |
| 93 | +- **BREAKING:** The letter Ø (used in Danish/Norwegian alphabet) is now |
| 94 | + considered the same as ∅ (empty set). It can no longer be used as a |
| 95 | + species/parameter. |
| 96 | +- **BREAKING:** When converting a Catalyst `ReactionSystem` to a ModelingToolkit |
| 97 | + system, for example an `ODESystem`, Catalyst defined functions like |
| 98 | + `hill(A,B,C,D)` are now replaced with the explicit rational function they |
| 99 | + represent in the equations of the generated system. For example `mm(X,v,K)` |
| 100 | + will be replaced with `v*X / (X + K)`. This can be disabled by passing the |
| 101 | + keyword argument `expand_catalyst_funs = false`. e.g. |
| 102 | + ```julia |
| 103 | + using Catalyst |
| 104 | + rn = @reaction_network begin |
| 105 | + hill(X,v,K,n), A --> 0 |
| 106 | + end |
| 107 | + osys = convert(ODESystem, rn) |
| 108 | + ``` |
| 109 | + generates an ODE system with `D(A) ~ -((v*A(t)*(X^n)) / (K^n + X^n))`, while |
| 110 | + ```julia |
| 111 | + osys = convert(ODESystem, rn; expand_catalyst_funs = false) |
| 112 | + ``` |
| 113 | + generates an ODE system with `D(A) ~ -A(t)*hill(X, v, K, n)`. This keyword |
| 114 | + argument can also be passed to problems defined over `ReactionSystem`s, i.e. |
| 115 | + when calling `ODEProblem(rn, u0, tspan, p; expand_catalyst_funs = false)`. |
| 116 | +- It is no longer recommended to install and use the full OrdinaryDiffEq library |
| 117 | + to access specific ODE solvers. Instead, only install the specific |
| 118 | + OrdinaryDiffEq sub-libraries that contain the desired solver. This |
| 119 | + significantly reduces installation and package loading times. I.e. to use the |
| 120 | + default solver that auto-switches between explicit and implicit methods, |
| 121 | + install `OrdinaryDiffEqDefault`. To use `Tsit5` install `OrdinaryDiffEqTsit5`, |
| 122 | + etc. The possible sub-libraries, each containing different solvers, can be |
| 123 | + viewed [here](https://github.com/SciML/OrdinaryDiffEq.jl/tree/master/lib). |
| 124 | +- It should now be safe to use `remake` on problems which have had conservation |
| 125 | + laws removed with the exception of `NonlinearProblem`s or `NonlinearSystem`s. |
| 126 | + For NonlinearProblems it is safe to use `remake` if only updating `u0` values, |
| 127 | + but it is not safe to update the value of the conserved constant, `Γ`. See |
| 128 | + [the FAQ](https://docs.sciml.ai/Catalyst/stable/faqs/#faq_remake_nonlinprob) |
| 129 | + for details. |
| 130 | +- Functional (e.g. time-dependent) parameters can now be used in Catalyst |
| 131 | + models. These can e.g. be used to incorporate arbitrary time-dependent |
| 132 | + functions (as a parameter) in a model. For more details on how to use these, |
| 133 | + please read: |
| 134 | + https://docs.sciml.ai/Catalyst/stable/model_creation/functional_parameters/. |
51 | 135 | - Scoped species/variables/parameters are now treated similar to the latest MTK |
52 | 136 | releases (≥ 9.49). |
53 | | -- The structural identifiability extension is currently disabled due to issues |
54 | | - StructuralIdentifiability has with Julia 1.10.5 and 1.11. |
55 | 137 | - A tutorial on making interactive plot displays using Makie has been added. |
56 | 138 | - The BifurcationKit extension has been updated to v.4. |
57 | | -- 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: |
| 139 | +- There is a new DSL option `@require_declaration` that will turn off automatic |
| 140 | + inferring for species, parameters, and variables in the DSL. For example, the |
| 141 | + following will now error: |
58 | 142 | ```julia |
59 | 143 | rn = @reaction_network begin |
60 | 144 | @require_declaration |
|
70 | 154 | (k1, k2), A <--> B |
71 | 155 | end |
72 | 156 | ``` |
73 | | -- 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. |
74 | | - ```julia |
75 | | - using Catalyst, GraphMakie, GLMakie |
76 | | - brusselator = @reaction_network begin |
77 | | - A, ∅ --> X |
78 | | - 1, 2X + Y --> 3X |
79 | | - B, X --> Y |
80 | | - 1, X --> ∅ |
81 | | - end |
82 | | - plot_network(brusselator) |
83 | | - ``` |
84 | | -- The letter Ø (used in Danish/Norwegian alphabet) is now conisdred the same as ∅ (empty set). It can no longer be used as a species/parameter. |
85 | | - |
| 157 | + |
86 | 158 | ## Catalyst 14.4.1 |
87 | 159 | - Support for user-defined functions on the RHS when providing coupled equations |
88 | 160 | for CRNs using the @equations macro. For example, the following now works: |
|
0 commit comments