ModelingToolkit... documenting my models

[BLI]

A recurring problem as my ModelingToolkit [MTK] models get more complex… I am running a MTK model developed for my students, i.e., the model is complete in that it runs.

I now have to create a problem document for the students, where I provide model parameters, initial values for unknowns, etc. in (LaTeX) tables.

To illustrate my “problem”, as part of the model “class” I create using macro @mtkmodel, I have the following section:

# Model parameters
    @parameters begin
        # Constant 
        R = 8.314,              [description = "Ideal gas constant, J/mol.K"]
        F = 9.649e4,            [description = "Faraday constant, C/mol"]
        p_o = 1e5,              [description = "Standard state pressure, Pa"]
        # Parameters
        # -- general parameters

The list of parameters is much longer than what is shown here, copying and pasting into LaTeX is error-prone, and perhaps I’m lazy. But …

• Is there some way to parse the model that I make by @mtkmodel and convert parameters (and variables?) into tables with, say, parameter names in the first column, values in the second column, and the description text string as comments in the third column?

I have not started to experiment with assigning units to parameters, variables, etc. If that is done, it would, of course, be even better to associate the units directly with the parameter values (e.g., using the \unittwo command).

OK – I know this is a “luxury” problem, but some say that lazyness is one of the driving forces of progress . One possibility would perhaps be to convert the parameters into a dataframe, and then use PrettyTables to produce the LaTeX code. Or, it could probably also be done directly.

• Perhaps there already is functionality for this?

[ChrisRackauckas]

@BLI

• Is there some way to parse the model that I make by @mtkmodel and convert parameters (and variables?) into tables with, say, parameter names in the first column, values in the second column, and the description text string as comments in the third column?

dump_variable_metadata(p), dump_parameters(sys), etc.

That at least puts it in the Tables.jl iterator form.

@cryptic.ax didn’t you have some example making a pretty table from the whole system?

I wouldn’t be opposed to some extensions so that something like DataFrame(sys) just works for this kind of thing, dump_system, etc.

This sounds like a great thing to help us build

[cryptic.ax]

I don’t recall making a table

dump_parameters/dump_unknowns returns an array of NamedTuples, so it’s not a proper Tables.jl interface yet but turning it into one and doing the DataFrame transform is not a huge jump.

[BLI]

Sounds great. You guys have made many more models than I have, and are much better versed in the structure of MTK. Extending my example…

# Model parameters
    @parameters begin
        # Constant 
        R = 8.314,              [unit = u"J/mol/K", description = "Ideal gas constant, J/mol.K"]
        F = 9.649e4,            [description = "Faraday constant, C/mol"]
        p_o = 1e5,              [description = "Standard state pressure, Pa"]
        # Parameters
        # -- general parameters
    @variables begin
        x(t)=1,     [unit = u"kmol", description="Something..."]
        y(t),         [unit = u"mol/s", description="Algebraic variable..."]
    end

Questions/things to think about:

• Should units be placed in a separate column? Perhaps – that might be simpler? Alternative is to merge the unit with the number, e.g., using some \unittwo{}{} structure where the first braces hold the number and the second braces hold the unit. That is, however, a LaTeX thing, and not a DataFrame thing.
• Some keyword values should perhaps be neglected? (Like the value of keyword connect, icons, etc.]
• Should variables be simplified by removing the independent variable(s)? E.g., x(t) → x, etc.
• Should only variables that have been assigned a numeric value be “dumped”, e.g., x but not y? I’m not sure of this. In any ways, it is simple to do this in post by manipulating data frames…

I know it is poor practice to add unrelated questions, but…

• Unit support… is the actual numeric value suggested by the user used, or is there some fancy “behind the scenes” change of values so that the model becomes unit-wise consistent?
• So… if I specify a membrane thickness in micrometers, say, but it is necessary to use the thickness in cm in order to have model consistency, is that handled automagically?

[cryptic.ax]

Should units be placed in a separate column? Perhaps – that might be simpler? Alternative is to merge the unit with the number, e.g., using some \unittwo{}{} structure where the first braces hold the number and the second braces hold the unit. That is, however, a LaTeX thing, and not a DataFrame thing.

I’d definitely prefer the unit in a column over LaTeX which we’d need to manually generate, then deserialize back to the unit to use with Unitful/DynamicQuantities anyway

Some keyword values should perhaps be neglected?

Should only variables that have been assigned a numeric value be “dumped”, e.g., x but not y?

I’d favor including all metadata, and allowing users to subset accordingly. It’s easier to ignore data you don’t need than get data you don’t have.

Should variables be simplified by removing the independent variable(s)?

I don’t think so. Whether a variable/parameter is time-dependent or not is useful information, especially with discrete variables being parameters.

Unit support… is the actual numeric value suggested by the user used, or is there some fancy “behind the scenes” change of values so that the model becomes unit-wise consistent?
So… if I specify a membrane thickness in micrometers, say, but it is necessary to use the thickness in cm in order to have model consistency, is that handled automagically?

I haven’t dealt with models with units much if at all so I’m not 100% sure on the answers to your questions, but am fairly certain that we only support SI units at the moment.

[BLI]

@cryptic.ax

but am fairly certain that we only support SI units at the moment.

That makes sense. A key cause of modeling mistakes is due to mismatched units [both my own experience, and what I have observed students do…]. So a system that can handle that is super useful. But probably somewhat tricky, and perhaps not the first thing to do…

I think Modelica only uses units to “inform” the reader of the code, and doesn’t actually change values.