MTK v11 documentation -- `System` constructor?

[B-LIE]

How is the System constructor meant to be used❓

I have looked into the System docstring:

using ModelingToolkit
?System

It seems like the new structure is as follows:

System(eqs, iv; kwargs)

where a number of kwargs are listed, and name is a required kwarg. Also, there are specialized structures (multiple dispatch, I assume), e.g.

System(eqs, iv, dvs, ps; kwargs)

In addition to the listed kwargs, the docstring states that field names can be used as keywords, e.g., unknowns and ps.

Question 1: I have tried both of the above constructor signatures. The second one (System(eqs,t,vars,params; name=name)) works, but I couldn't get the first one (System(eqs,t; name=name, unknowns=vars, ps=params)) to work.

Question 2: Is the recommended/"future proof" syntax the one with 2 positional arguments + kwargs? Or the one with 4 positional arguments (assuming DAEs).

Question 3: I have also tried to initialize a "state" (differential variable) with a symbolic expression...

# I have already defined rho and A in a @parameters block...

#Attempt 1
@variables m(t)=1.5*rho*A

# Attempt 2
System(eqs,t,vars,params;name=name, initialization_eqs=[m ~ 1.5*rho*A])

# Attempt 3
System(eqs,t,vars,params;name=name, initial_conditions=[m => 1.5*rho*A])

Attempts 1 & 2 kind of work if I do not specify values in the ODEProblem. However, they both fail with an error message of over-specification if I try to change the initial value of m in the ODEProblem.

Attempt 3, however, works.

... Does this imply that initial_conditions is the keyword to use for specifying initial values of variables? There is also a field guesses... is there any advantage in specifying guesses in the System constructor, instead of as metadata in the @variables begin...end block?

[AayushSabharwal]

It seems like the new structure is as follows:

The System(eqs, iv, dvs, ps) syntax is identical to the ODESystem syntax we had earlier. System(eqs, iv; kwargs...) attempts to discover the unknowns (dvs) and parameters (ps) from the equations and other information. The 4-argument constructor requires the user to provide the unknowns and parameters, and does no such automated discovery.

In addition to the listed kwargs, the docstring states that field names can be used as keywords, e.g., unknowns and ps.

That's mostly correct. I think the documentation is phrased a bit confusingly. unknowns and ps are specifically not keyword arguments, they are the third and fourth positional arguments respectively. brownians is the fifth positional argument, and is optional. All other fields are valid keyword arguments, though some fields are not public API and documented as such.

I think this answers Question 1 too.

Question 2: Is the recommended/"future proof" syntax the one with 2 positional arguments + kwargs? Or the one with 4 positional arguments (assuming DAEs).

When building a component library, I recommend the 4-argument version. It avoids ambiguity and issues where MTK may not be able to identify all the unknowns of your model.

Question 3: I have also tried to initialize a "state" (differential variable) with a symbolic expression...

The "default" provided for the variable m during its declaration is also a constraint during initialization. When this "default" (the value after = in the @variables declaration) is an expression involving other variables/parameters, the constraint is treated as a "binding". If it is a literal number, it is treated as an "initial condition". The difference between these two is documented in https://docs.sciml.ai/ModelingToolkit/stable/tutorials/initialization/#bindings_and_ics. For variables, both bindings and initial conditions are constraints during initialization. However, bindings are an immutable property of the model, and cannot be changed after building the System. In attempt 2, the constraint is phrased using initialization_eqs. Like bindings, these are immutable initialization constraints. However, unlike bindings, constraints provided via initialization_eqs do not have to be explicit in a particular variable. For example, initialization_eqs = [x^2 + y^2 ~ 1] is perfectly valid.

Any initial values provided to ODEProblem are isomorphic to initial_conditions. Since bindings and initialization_eqs are an immutable property of the system, the constraint in Attempt 1 and Attempt 2 is present in the initialization addition to the constraint provided to ODEProblem. For example, if m => 1 was passed to ODEProblem, then the initialization system would contain equations like

m ~ 1.5 * rho * A
m ~ 1

Thus, there are two constraints for the variable m, causing the initialization to be overdetermined. If the values of rho and A are such that both constraints cannot be satisfied simultaneously, this results in the InitialFailure you observe.

In Attempt 3, the constraint is provided using initial_conditions. This is very similar to the defaults in prior versions of MTK. They are mutable - so mutating ModelingToolkit.get_initial_conditions(sys) after system construction is valid. Values provided to ODEProblem are equivalent to changing initial_conditions. So in Attempt 3, the m => 1 constraint passed to ODEProblem overrides the m => 1.5 * rho * A constraint passed to the initial_conditions keyword of System. As a result, the initialization system is not overdetermined.

Does this imply that initial_conditions is the keyword to use for specifying initial values of variables?

I hope this question is answered by my above description. Please let me know if additional clarification is required.

There is also a field guesses... is there any advantage in specifying guesses in the System constructor, instead of as metadata in the @variables begin...end block?

I personally prefer using the keyword argument. It is slightly more robust and I'm not a fan of variable metadata in the first place. When building a System, MTK will parse the variable metadata to extract guesses/defaults/etc. and store them in the system, identically to how they would be if they were passed as keyword arguments. As long as you're using @named to build your systems, either approach will work.

[B-LIE]

Thanks! Very clear answers!

I was also wondering about keyword observed, but didn't raise a question about that. To clarify my question, in the original symbolic model prior to simplification, let vars be the symbolic variables. This should be equal to the collection of all dvs (dependent variables) in all components constituting the symbolic model.

Then, after simplification/compilation, vars is equal to the union of unknowns and "observed variables" -- except for the possibility that simplification may have introduced extra variables in the index reduction process.

Question: If I provide dvs in the third position, and then want to add observed equations, I should not remove the "observed variables" from dvs? Or should I?

[AayushSabharwal]

The observed keyword is public API to allow users to build models that do not go through mtkcompile - essentially by manually eliminating variables. The contract for observed is that it is a topologically sorted list of explicit equations. In other words, for every eliminated variable x, the equation x ~ ... should be present in observed. If the RHS of the equation depends on other eliminated variables, the equations for those variables should occur prior to this one. These eliminated variables should then also not be present in unknowns.

If you intend to call mtkcompile, do not provide observed. All variables, whether you intend for them to be eliminated or not, should be present in dvs. All equations should be passed as the first argument to System.

[B-LIE]

Ah. I just saw that you released a new MTK version just now, that makes the bounds meta data available. Or more precisely, that a specified bounds is now passed on to the nonlinear solver (e.g., for initialization).

bounds is not mentioned as a field in System, so I guess the only way to provide it is as metadata.

I assume that both bounds and guess/guesses can be used simultaneously. The only "problem" I foresee is if the guessvalue does not satisfy the bounds tuple??

[AayushSabharwal]

bounds is not mentioned as a field in System, so I guess the only way to provide it is as metadata.

Yes, eventually I do plan to put it in the system. But it is not there yet.

I assume that both bounds and guess/guesses can be used simultaneously.

Yes.

The only "problem" I foresee is if the guessvalue does not satisfy the bounds tuple??

I don't think that should be an issue.