Chemistry functionality remake

[TorkelE]

Changes:

• Add docstrings to chemistry-related functions.
• Adds documentation for chemistry-related functionality.
• Simplifies internal code for chemistry-related functionality.
• Redo @compound syntax:

@variables t
@species C(t) O(t)
@compound CO2(t) ~ C + 2O 

• Enables @compound to see variables, e.g.

@variables t
@species C(t) O(t)
o = O
@compound CO2 ~ C + 2o

• Add the compounds macro, enabling the creation of multiple compounds simultaneously:

@variables t
@species C(t) O(t)
@compounds begin
    O2 ~ 2O
    CO2 ~ C + 2O
end

• Adds the compounds option to the DSL, enabling the declaration of compounds within it (the components must be designated as a species, and are not ifered).

[TorkelE]

Ok, this shoudl be ready now. I will have a look tomorrow with fresh eyes though to be sure there are no errors (there are a couple in the docs for a starter that I need to fix).

One feature that it might make sense to add is a balance_reaction_network function, which applied balance_reaction on each reaction of a ReactionSystem, and returns a new ReactionSystem with balanced reactions.

Finally, I don't think setting metadata is supported for compounds, which probably should be the case, e.g.

@compound H2_2(t) [metadata=value] = 2H
@compounds begin
    O2  [metadata=value]= 2O 
end

[TorkelE]

Ok, this should be ready now.

[isaacsas]

Yes, we should support metadata for compounds.

Should we instead infer the arguments of the compound from the species that make it up?

[isaacsas]

I.e. if the species depend on time t the compound does, but if they depend on s then it does?

[TorkelE]

That's a good point. Having a compound with a different independent variable than its compositions would be weird, right? If this is indeed the case I will change it so that the compound takes its components iv (and throw an error if they have different ones.

Supporting metadata should be easy, e.g.

@compounds begin
    O2  [metadata=value] = 2O 
end

But if we want to also give a default value, how would we phrase that?

@compounds begin
    O2  [metadata=value] = 2O =1.0
end

?

[isaacsas]

Or the compound could be the union of the ivs of the components I guess (for mixed spatial problems).

[isaacsas]

Yeah, we should allow default values. Maybe we should use something else to indicate the formula in terms of species?

@compounds begin
    O2  [metadata=value] = 1.0 ~ 2O
end

But I’m open to other suggestions.

[TorkelE]

I will have a look tomorrow at what is actually possible notations using metaprogramming. Leaning towards keeping the current notation, and then add something if default values are required.

[isaacsas]

The one reason for ~ is then it looks like an MTK equation.

[TorkelE]

With default values being stored in the metadata, would it be possible to define it there? Doesn't seem to work perfectly though, e.g.

@variables t X(t) [defaultvalue=1.0]

and other alternatives I've tried fail. Stuff like this:

@compound CO2 = 0.0 = C + 2O 

would be possible.

I think that, for now, I will leave setting default values unsupported (unless we can make it work along the line like [defaultvalue=1.0], in which case there is a workaround. The feature seems incredibly niche, and given that we cannot know whether anyone will actually use compounds a year from now (not to talk about setting default values for them), I don't want to sink too much time into it. If I see an opportunity to do it easily while fixing the metadata stuff I might have a go at it though.

[isaacsas]

OK, if it isn't easy to do maybe we should hold off on making an update then. I'd prefer not to potentially break the interface twice (i.e. once with this PR, and then potentially again when we fix it to support metadata and initial values).

[TorkelE]

Updated how @compound (and similar) have its syntax:

@compound H2O_1 ~ 2H + O
@compound H2O_2, [output=true] ~ 2H + O
@compound (H2O_3 = 1.5) ~ 2H + O
@compound (H2O_4 = 4, [output=true]) ~ 2H + O
@compound (H2O_5 = p1, [output=true]) ~ 2H + p2*O

Currently, I have not been able to figure out how to extract the independent variable from the rhs, so just set it to t. Once I've figured that out this should be ready.

[TorkelE]

Sorry, I've been juggling 10 branches back and forth and I finally messed up. I accidentally rebased this on #713 (I meant to do that for the structural identifiability PR, which needs to be on that PR to be able to handle mm and hill functions). Talked to Avik and there doesn't seem to be a good solution more than waiting with merging this until #713 is merged.

[TorkelE]

Updates:

• Improved internal formatting further.
• Change syntax to @compound (H2O_2, [output=true]) ~ 2H + O (parenthesis added).
• Permits adding ivs in the compound.
• If the components have more than one iv combined, ivs must be provided in the compound.

[isaacsas]

Does balancing with reactions involving compounds of compounds work / is it tested?

@TorkelE I'm fine with merging once you've addressed these comments -- I don't need to review again. If compounds of compounds don't work in balancing that should be mentioned in the tutorial and docstring though (or made to work).

[TorkelE]

Compound of compounds does not work. Thought it was mentioned, but will add that in (and in docstring as well).

[isaacsas]

Can we add an error message in balance_reaction if we detect one of the species is a compound of compounds? That should be straightforward I'd hope.

[isaacsas]

(Unless I just missed that we already give an error there.)

[TorkelE]

Checked, no there is not such error. I will add that.

[isaacsas]

OK, thanks! Once you've made your updates feel free to merge if tests pass. (They might not until we get the binomial issue in Symbolics fixed.)

[TorkelE]

This is done now. Will give it a day or two to see what happens with the binomial issue before merging though (in case there is some problem with that).

[isaacsas]

We need to wait till we can run tests to completion before merging anything.

[TorkelE]

yes