ModelingToolkitStandardLibrary.jl

When modeling physical systems, you can choose between a velocity-based domain or a position-based domain. Mathematically, both approaches solve the same underlying differential equations. For example, in a mass-spring-damper system, the velocity domain uses the spring stretch $\Delta s$ as a state, while the position domain uses the absolute position $s$ and calculates stretch as $\Delta s = s - s_{b_0} - l$.

Numerical differences between these two formulations are negligible (typically much less than $10^{-9}$), meaning the choice between them is primarily a matter of modeling preference rather than accuracy.

# Example of plotting the numerical difference between velocity and position domain solutions
plot(title = "numerical difference: vel. vs. pos. domain", xlabel = "time [s]",
    ylabel = "solv[bv.v] .- solp[bp.v]")
time = 0:0.1:10
plot!(time, (solv(time)[bv.v] .- solp(time)[bp.v]), label = "")

The ModelingToolkitStandardLibrary provides two ways to model mechanical translation. Choosing between them depends on whether your model requires absolute position information or just velocities.

1. Velocity-based Domain (Mechanical.Translational)

• Across Variable: Velocity ($v$).
• Pros: Simpler initialization; lower-order equations.
• Cons: Does not track absolute position ($s$) by default. To get position, you must either use a component that supports an initial position parameter or implement a sensor.
• Usage: Use when the model is primarily concerned with forces, velocities, and accelerations.

2. Position-based Domain (Mechanical.TranslationalPosition)

• Across Variable: Position ($s$).
• Pros: Provides direct access to absolute position states.
• Cons: Requires more initial condition information (e.g., natural spring length, absolute fixed positions) to be properly defined.
• Usage: Use when absolute position is a primary variable of interest in your simulation.

The ModelingToolkitStandardLibrary.jl follows a sign convention (consistent with the Modelica Standard Library) to ensure physical consistency when connecting components.

The Rule: An input component that specifies a through variable (e.g., force, current, mass flow) must be defined such that a positive value for that flow variable represents the accumulation of the associated across variable (e.g., velocity, voltage, pressure/density) over time in the connected component.

Mathematically, the energy dissipation equation follows: $$\frac{\partial \text{across}}{\partial t} = \text{through input}$$

Implementation Pattern: When defining an input component, you typically write an opposite equality for the connector's through variable to align the component and port connection. For example, if a force f is leaving a port, the equation should be port.f ~ -f.

# Correct sign convention for a force input component
@mtkmodel ConstantForce begin
    @parameters begin
        f = 0
    end
    @components begin
        flange = MechanicalPort()
    end
    @equations begin
        flange.f ~ -f # force is leaving the port
    end
end

In acausal physical network modeling, every physical domain connector defines two types of variables: a Through variable and an Across variable. This relationship is fundamental to how energy dissipation and flow are modeled.

• Through variable: Typically a time derivative of a conserved quantity (e.g., current, force).
• Across variable: The conserved quantity itself (e.g., voltage, velocity, position).

Mathematical Relationship

For energy dissipation and flow, the relationship generally follows these patterns:

Energy Dissipation (Storage): $$\frac{\partial \text{across}}{\partial t} \cdot c_1 = \text{through}$$

Flow: $$\text{through} \cdot c_2 = \text{across}$$

Domain Examples

Linear analysis in ModelingToolkitStandardLibrary is performed by inserting an AnalysisPoint into a model. An AnalysisPoint acts as a probe or a break in the signal flow, allowing you to extract linearized representations of the system at specific locations.

Creating Analysis Points

You can create an analysis point in two ways:

1. Automatically via connect: When connecting two causal components, pass a symbol as the middle argument. This creates a causal analysis point where the signal flows from the first argument to the third.

   connect(comp1.output, :analysis_point_name, comp2.input)

2. Explicitly: Using the AnalysisPoint constructor.

Important: Causality

Analysis points are causal. The order of arguments in connect(out, :name, in) defines the direction of information flow. Reversing the order (connect(in, :name, out)) changes the directionality of the analysis point.

# Automatic creation of an analysis point named :plant_output
connect(P.output, :plant_output, C.input)