Stream connector equations missing when used in subsystem

[cstjean]

Describe the bug 🐞

Stream connector equations are present when used to connect connectors directly, but absent when used in a submodel.

Relatedly, I have (not shared, not MWE'ed) model code with only two components connected via stream, that unexpectedly fails, but succeeds when the connector type is across.

Expected behavior

Stream equations should be there.

A system of two components connected via across should be equivalent to a connection via stream (AFAIK!)

Minimal Reproducible Example 👇

From https://discourse.julialang.org/t/stream-connections-of-subsystems/121279, by @se-schmitt. See also SciML/ProcessSimulator.jl#17

using ModelingToolkit
using ModelingToolkit: t_nounits as t

@connector TwoPhaseFluidPort begin
    @variables begin
        h_outflow(t) = 0.0, [connect = Stream]
        m_flow(t) = 0.0, [connect = Flow]
        P(t) = 0.0
    end
end

@mtkmodel SubSys begin
    @components begin
        sp1 = TwoPhaseFluidPort()
        sp2 = TwoPhaseFluidPort()
    end
end

@mtkmodel Sys begin
    @components begin
        subsys = SubSys()
    end
    @equations begin
        connect(subsys.sp1, subsys.sp2)
    end
end

@named mysys = Sys()

sys_exp = expand_connections(mysys)
eqs = equations(sys_exp)

# Output:
# 2-element Vector{Equation}:
# 0 ~ subsys₊sp1₊m_flow(t) + subsys₊sp2₊m_flow(t)
# subsys₊sp1₊P(t) ~ subsys₊sp2₊P(t)

However, when the components are directly inside a single @mtkmodel, the equations are there:

 @mtkmodel Sys2 begin
    @components begin
        sp1 = TwoPhaseFluidPort()
        sp2 = TwoPhaseFluidPort()
    end
    @equations begin
        connect(sp1, sp2)
    end
end

@named sys2 = Sys2()

sys2_exp = expand_connections(sys2)
eqs2 = equations(sys2_exp)

# Output:
# 6-element Vector{Equation}:
#  sp1₊h_outflow(t) ~ ModelingToolkit.instream(sp2₊h_outflow(t))
#  sp2₊h_outflow(t) ~ ModelingToolkit.instream(sp1₊h_outflow(t))
#  0 ~ sp1₊m_flow(t)
#  0 ~ sp2₊m_flow(t)
#  0 ~ -sp1₊m_flow(t) - sp2₊m_flow(t)
#  sp1₊P(t) ~ sp2₊P(t)

Another demonstration of the problem is that when taking out the , [connect = Stream] part (making it across), the number of equations for my_sys grows by 1 (bad; stream should have more equations), but shrinks by 1 for sys2 (as expected).

Environment (please complete the following information):

• Output of using Pkg; Pkg.status()

MTK 9.49.0

• Output of versioninfo()

Julia 1.10.5

[AayushSabharwal]

MTK's connectors are designed according to https://specification.modelica.org/master/connectors-and-connections.html. This might be intentional behavior given that specification and the discussion in #3008. I'm working on figuring this out myself to provide a concrete reason for this behavior.

[AayushSabharwal]

This is intentional. In the "not working" example, both connectors are "inside connectors". The spec mentions:

For inside connectors (see section 9.1.2), variables with the stream prefix do not lead to connection equations.

Which justifies the missing stream equations.

In the second example with 6 equations, the equations setting flow variables to zero comes from the fact that both connectors are outer connectors. Outer connectors are expected to connect to other components. If they were, those equations would not be generated.

[cstjean]

For inside connectors (see section 9.1.2), variables with the stream prefix do not lead to connection equations.

This confused me. In the standard @mtkmodel System that contains a bunch of components and connects them, aren't all connectors "inside connectors"? Do we never get connection equations in this case? However, the next line of the spec says:

Connection equations with stream variables are generated in a model when using inStream or actualStream, see section 15.2 and section 15.3.

And indeed, in my own code, I had forgotten instream. When I use it,

Relatedly, I have (not shared, not MWE'ed) model code with only two components connected via stream, that unexpectedly fails, but succeeds when the connector type is across.

that now succeeds, 👍

I'll close this, but if any of the above is mistaken, I'd appreciate a correction.

Thank you for investigating!

[AayushSabharwal]

This confused me. In the standard @mtkmodel System that contains a bunch of components and connects them, aren't all connectors "inside connectors"?

The definition of inside and outside connectors is in https://specification.modelica.org/master/connectors-and-connections.html#inside-and-outside-connectors. They are defined with respect to a component. sp1 and sp2 are inside connectors of Sys, but outside connectors of SubSys and Sys2. Since the connect equations are in Sys, they are treated as inside connectors. In Sys2, they are treated as outside connectors while generating equations.

[cstjean]

Right, I understand this explanation for Sys and Sys2. But for example, in the tutorial, all connect statements are for inside connectors, right? So the language

For inside connectors (see section 9.1.2), variables with the stream prefix do not lead to connection equations.

suggests that we couldn't use stream connections in such a system. However it looks like this is not the correct interpretation, since

Connection equations with stream variables are generated in a model when using inStream or actualStream, see section 15.2 and section 15.3.

And indeed inside connectors that use instream do lead to connection equations.

[matthew-kapp]

How does one use instream?

[matthew-kapp]

@cstjean Could you please share the code that makes it work? Where do you call instream?

[cstjean]

I'm sorry, I don't have code that I can easily share. Rapid sketch:

@connector FluidPort begin
    @variables begin
        density(t) = 0.0, [connect = Stream]
        mass_flow(t) = 0.0, [connect = Flow]
        P(t) = 0.0  # you need that variable even if you don't use pressure
    end
end

@mtkmodel Source begin
    @components begin
        outlet = FluidPort()
    end
    @equations begin
         outlet.density ~ 0.8
         outlet.m_flow ~ 10
    end
end

@mtkmodel Tank begin
    @components begin
        inlet = FluidPort()
    end
    @variables begin
        total_mass = 0
        density = 0.3
    end
    @equations begin
         D(total_mass) ~ inlet.mass_flow
         D(density) ~ whatever + somethingsomething * instream(inlet.density) # instream is necessary for all uses of `inlet.density`
         inlet.density ~ -99999  # this is often necessary for MTK :( It specifies the density during backflow. I set it to -99999 to detect problems (since I don't have backflows) but it's super wonky
    end
end

@mtkmodel Sys begin
    @components begin
        source = Source()
        tank = Tank()
    end
    @equations begin
        connect(source.outlet, tank.inlet)
    end
end

I didn't run this, but hopefully it can give you a starting point. Getting to that basic system took me a lot of trial and error, it's not a polished part of MTK.