Merge branch 'main' into analysis_points

Author: baggepinnen

.github/workflows/Documentation.yml

@@ -21,4 +21,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+        run: julia --project=docs/ --code-coverage=user docs/make.jl
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v1
+        with:
+          file: lcov.info

.github/workflows/Invalidations.yml

@@ -0,0 +1,40 @@
+name: Invalidations
+
+on:
+  pull_request:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: always.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  evaluate:
+    # Only run on PRs to the default branch.
+    # In the PR trigger above branches can be specified only explicitly whereas this check should work for master, main, or any other default branch
+    if: github.base_ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+    - uses: julia-actions/setup-julia@v1
+      with:
+        version: '1'
+    - uses: actions/checkout@v3
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_pr
+
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.repository.default_branch }}
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_default
+    
+    - name: Report invalidation counts
+      run: |
+        echo "Invalidations on default branch: ${{ steps.invs_default.outputs.total }} (${{ steps.invs_default.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+        echo "This branch: ${{ steps.invs_pr.outputs.total }} (${{ steps.invs_pr.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+    - name: Check if the PR does increase number of invalidations
+      if: steps.invs_pr.outputs.total > steps.invs_default.outputs.total
+      run: exit 1

Project.toml

@@ -7,21 +7,20 @@ version = "1.5.0"
 IfElse = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
-OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 
 [compat]
 IfElse = "0.1"
 ModelingToolkit = "8"
 OffsetArrays = "1"
-OrdinaryDiffEq = "5.56, 6"
-Symbolics = "0.1, 1, 2, 3, 4"
+Symbolics = "4.9"
 julia = "1.6"
 
 [extras]
 ControlSystemsBase = "aaaaaaaa-a6ca-5380-bf3e-84a91bcd477e"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["SafeTestsets", "Test", "ControlSystemsBase"]
+test = ["OrdinaryDiffEq", "SafeTestsets", "Test", "ControlSystemsBase"]

README.md

@@ -1,8 +1,14 @@
 # ModelingToolkitStandardLibrary.jl
 
-[![CI](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/actions/workflows/CI.yml)
+[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://mtkstdlib.sciml.ai/stable/)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://mtkstdlib.sciml.ai/dev/)
+[![Global Docs](https://img.shields.io/badge/docs-SciML-blue.svg)](https://docs.sciml.ai/dev/modules/ModelingToolkitStandardLibrary/)
+
+[![codecov](https://codecov.io/gh/SciML/ModelingToolkitStandardLibrary.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/SciML/ModelingToolkitStandardLibrary.jl)
+[![Build Status](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/workflows/CI/badge.svg)](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/actions?query=workflow%3ACI)
+
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 The ModelingToolkit Standard Library is a standard library of components to model the world and beyond.
 

docs/src/API/mechanical.md

@@ -34,10 +34,21 @@ Inertia
 Spring
 Damper
 IdealGear
+RotationalFriction
 ```
 
 ### Rotational Sources
 
 ```@docs
 Torque
-```
+Speed
+```
+
+### Rotational Sensors
+
+```@docs
+AngleSensor
+SpeedSensor
+TorqueSensor
+RelSpeedSensor
+```

docs/src/tutorials/custom_component.md

@@ -99,7 +99,7 @@ connections = [
     connect(Ro.n, Gnd.g)
 ]
 
-@named model = ODESystem(connections, t, systems=[L, Ro, G, C1, C2, Nr])
+@named model = ODESystem(connections, t, systems=[L, Ro, G, C1, C2, Nr, Gnd])
 nothing # hide
 ```
 

src/Blocks/Blocks.jl

@@ -2,7 +2,7 @@
 The module `Blocks` contains common input-output components, referred to as blocks.
 """
 module Blocks
-using ModelingToolkit, Symbolics, OrdinaryDiffEq
+using ModelingToolkit, Symbolics
 using IfElse: ifelse
 
 @parameters t

src/Blocks/continuous.jl

@@ -111,7 +111,7 @@ Critical damping corresponds to `d=1`, which yields the fastest step response wi
 
 # Parameters:
 - `k`: Gain
-- `w`: Angular frequency
+- `w`: [`rad/s`] Angular frequency
 - `d`: Damping
 - `x_start`: Initial value of state (output)
 - `xd_start`: Initial value of derivative of state (output)
@@ -305,7 +305,7 @@ where the transfer function for the derivative includes additional filtering, se
 - `wd`: [0,1] Set-point weighting in the derivative part.
 - `Nd`: [1/s] Derivative limit, limits the derivative gain to Nd/Td. Reasonable values are ∈ [8, 20]. A higher value gives a better approximation of an ideal derivative at the expense of higher noise amplification.
 - `Ni`: `Ni*Ti` controls the time constant `Ta` of anti-windup tracking. A common (default) choice is `Ta = √(Ti*Td)` which is realized by `Ni = √(Td / Ti)`. Anti-windup can be effectively turned off by setting `Ni = Inf`.
-` `gains`: If `gains = true`, `Ti` and `Td` will be interpreted as gains with a fundamental PID transfer function on parallel form `ki=Ti, kd=Td, k + ki/s + kd*s`
+- `gains`: If `gains = true`, `Ti` and `Td` will be interpreted as gains with a fundamental PID transfer function on parallel form `ki=Ti, kd=Td, k + ki/s + kd*s`.
 
 # Connectors:
 - `reference`
@@ -438,7 +438,7 @@ function StateSpace(; A, B, C, D = nothing, x_start = zeros(size(A, 1)), name)
     end
     @named input = RealInput(nin = nu)
     @named output = RealOutput(nout = ny)
-    @variables x[1:nx](t) = x_start
+    @variables x(t)[1:nx] = x_start
     # pars = @parameters A=A B=B C=C D=D # This is buggy
     eqs = [ # FIXME: if array equations work
         [Differential(t)(x[i]) ~ sum(A[i, k] * x[k] for k in 1:nx) +

src/Blocks/utils.jl

@@ -2,7 +2,7 @@
     if nin == 1
         @variables u(t)=u_start [input = true]
     else
-        @variables u[1:nin](t)=u_start [input = true]
+        @variables u(t)[1:nin]=u_start [input = true]
         u = collect(u)
     end
     ODESystem(Equation[], t, [u...], []; name = name)
@@ -24,7 +24,7 @@ Connector with one input signal of type Real.
     if nout == 1
         @variables u(t)=u_start [output = true]
     else
-        @variables u[1:nout](t)=u_start [output = true]
+        @variables u(t)[1:nout]=u_start [output = true]
         u = collect(u)
     end
     ODESystem(Equation[], t, [u...], []; name = name)
@@ -45,7 +45,7 @@ Connector with one output signal of type Real.
 """
     SISO(;name, u_start=0.0, y_start=0.0)
 
-Single Input Single Output continuous control block.
+Single input single output (SISO) continuous system block.
 
 # Parameters:
 - `u_start`: Initial value for the input
@@ -66,7 +66,7 @@ end
 """
     MIMO(;name, nin=1, nout=1, u_start=zeros(nin), y_start=zeros(nout))
 
-Base class for a multiple Input multiple Output continuous control block.
+Base class for a multiple input multiple output (MIMO) continuous system block.
 
 # Parameters:
 - `nin`: Input dimension
@@ -78,8 +78,8 @@ function MIMO(; name, nin = 1, nout = 1, u_start = zeros(nin), y_start = zeros(n
     @named input = RealInput(nin = nin, u_start = u_start)
     @named output = RealOutput(nout = nout, u_start = y_start)
     @variables begin
-        u[1:nin](t) = u_start
-        y[1:nout](t) = y_start
+        u(t)[1:nin] = u_start
+        y(t)[1:nout] = y_start
     end
     eqs = [
         [u[i] ~ input.u[i] for i in 1:nin]...,

src/Electrical/Electrical.jl

@@ -4,7 +4,7 @@ This library contains electrical components to build up analog circuits.
 """
 module Electrical
 
-using ModelingToolkit, Symbolics, IfElse, OrdinaryDiffEq
+using ModelingToolkit, Symbolics, IfElse
 using OffsetArrays
 
 @parameters t

src/Mechanical/Rotational/Rotational.jl

@@ -3,19 +3,22 @@ Library to model 1-dimensional, rotational mechanical systems
 """
 module Rotational
 
-using ModelingToolkit, Symbolics, IfElse, OrdinaryDiffEq
+using ModelingToolkit, Symbolics, IfElse
 using ...Blocks: RealInput, RealOutput
 
 @parameters t
 D = Differential(t)
 
-export Flange
+export Flange, Support
 include("utils.jl")
 
-export Fixed, Inertia, Spring, Damper, IdealGear
+export Fixed, Inertia, Spring, Damper, IdealGear, RotationalFriction
 include("components.jl")
 
-export Torque
+export Torque, Speed
 include("sources.jl")
 
+export AngleSensor, SpeedSensor, TorqueSensor, RelSpeedSensor
+include("sensors.jl")
+
 end

src/Mechanical/Rotational/components.jl

@@ -3,8 +3,11 @@
 
 Flange fixed in housing at a given angle.
 
+# Connectors:
+- `flange` [Flange](@ref)
+
 # Parameters:
-- `phi0`: [rad] Fixed offset angle of housing
+- `phi0`: [`rad`] Fixed offset angle of housing
 """
 function Fixed(; name, phi0 = 0.0)
     @named flange = Flange()
@@ -18,16 +21,20 @@ end
 
 1D-rotational component with inertia.
 
-# Parameters:
-- `J`: [kg·m²] Moment of inertia 
-- `phi_start`: [rad] Initial value of absolute rotation angle of component 
-- `w_start`: [rad/s] Initial value of absolute angular velocity of component
-- `a_start`: [rad/s²] Initial value of absolute angular acceleration of component
-
 # States: 
-- `phi`: [rad] Absolute rotation angle of component 
-- `w`: [rad/s] Absolute angular velocity of component (= der(phi)) 
-- `a`: [rad/s²] Absolute angular acceleration of component (= der(w)) 
+- `phi`: [`rad`] Absolute rotation angle of component 
+- `w`: [`rad/s`] Absolute angular velocity of component (= D(phi)) 
+- `a`: [`rad/s²`] Absolute angular acceleration of component (= D(w)) 
+
+# Connectors:
+- `flange_a` [Flange](@ref) Left flange
+- `flange_b` [Flange](@ref) Right flange
+
+# Parameters:
+- `J`: [`kg·m²`] Moment of inertia 
+- `phi_start`: [`rad`] Initial value of absolute rotation angle of component 
+- `w_start`: [`rad/s`] Initial value of absolute angular velocity of component
+- `a_start`: [`rad/s²`] Initial value of absolute angular acceleration of component
 """
 function Inertia(; name, J, phi_start = 0.0, w_start = 0.0, a_start = 0.0)
     @named flange_a = Flange()
@@ -51,9 +58,17 @@ end
 
 Linear 1D rotational spring
 
+# States:
+- `phi_rel(t)`: [`rad`] Relative rotation angle (`flange_b.phi - flange_a.phi`)
+- `tau(t)`: [`N.m`] Torque between flanges (`flange_b.tau`)
+
+# Connectors:
+- `flange_a` [Flange](@ref)
+- `flange_b` [Flange](@ref)
+
 # Parameters:
-- `c`: [N.m/rad] Spring constant
-- `phi_rel0`: Unstretched spring angle
+- `c`: [`N.m/rad`] Spring constant
+- `phi_rel0`: [`rad`] Unstretched spring angle
 """
 function Spring(; name, c, phi_rel0 = 0.0)
     @named partial_comp = PartialCompliant()
@@ -71,8 +86,18 @@ end
 
 Linear 1D rotational damper
 
+# States:
+- `phi_rel(t)`: [`rad`] Relative rotation angle (= flange_b.phi - flange_a.phi)
+- `w_rel(t)`: [`rad/s`] Relative angular velocity (= D(phi_rel))
+- `a_rel(t)`: [`rad/s²`] Relative angular acceleration (= D(w_rel))
+- `tau(t)`: [`N.m`] Torque between flanges (= flange_b.tau)
+
+# Connectors:
+- `flange_a` [Flange](@ref)
+- `flange_b` [Flange](@ref)
+
 # Parameters:
-- `d`: [N.m.s/rad] Damping constant
+- `d`: [`N.m.s/rad`] Damping constant
 """
 function Damper(; name, d)
     @named partial_comp = PartialCompliantWithRelativeStates()
@@ -89,6 +114,15 @@ Ideal gear without inertia.
 
 This element characterizes any type of gear box which is fixed in the ground and which has one driving shaft and one driven shaft.
 
+# States:
+- `phi_a(t)`: [`rad`] Relative angle between shaft a and the support
+- `phi_b(t)`: [`rad`] Relative angle between shaft b and the support
+
+# Connectors:
+- `flange_a` [Flange](@ref)
+- `flange_b` [Flange](@ref)
+- `support` [Support](@ref) if `use_support == true`
+
 # Parameters:
 - `ratio`: Transmission ratio (flange_a.phi/flange_b.phi)
 - `use_support`: If support flange enabled, otherwise implicitly grounded
@@ -104,3 +138,43 @@ function IdealGear(; name, ratio, use_support = false)
            0 ~ ratio * flange_a.tau + flange_b.tau]
     extend(ODESystem(eqs, t, sts, [ratio]; name = name), partial_element)
 end
+
+"""
+    RotationalFriction(;name, f, tau_c, w_brk, tau_brk) 
+
+Models rotational friction with Stribeck effect, Coulomb friction and viscous friction between the two flanges.
+The friction torque is a function of the relative angular velocity between flange_a and flange_b.
+
+Friction model: "Armstrong, B. and C.C. de Wit, Friction Modeling and Compensation, The Control Handbook, CRC Press, 1995."
+
+# States:
+- `phi_rel(t)`: [`rad`] Relative rotation angle (= flange_b.phi - flange_a.phi)
+- `w_rel(t)`: [`rad/s`] Relative angular velocity (= D(phi_rel))
+- `a_rel(t)`: [`rad/s²`] Relative angular acceleration (= D(w_rel))
+- `tau(t)`: [`N.m`] Torque between flanges (= flange_b.tau)
+
+# Connectors:
+- `flange_a` [Flange](@ref)
+- `flange_b` [Flange](@ref)
+
+# Parameters:
+- `f`: [`N⋅m/(rad/s)`] Viscous friction coefficient 
+- `tau_c`: [`N⋅m`] Coulomb friction torque
+- `w_brk`: [`rad/s`] Breakaway friction velocity 
+- `tau_brk`: [`N⋅m`] Breakaway friction torque
+"""
+function RotationalFriction(; name, f, tau_c, w_brk, tau_brk)
+    @named partial_comp = PartialCompliantWithRelativeStates()
+    @unpack w_rel, tau = partial_comp
+    pars = @parameters f=f tau_c=tau_c w_brk=w_brk tau_brk=tau_brk
+
+    str_scale = sqrt(2 * exp(1)) * (tau_brk - tau_c)
+    w_st = w_brk * sqrt(2)
+    w_coul = w_brk / 10
+
+    eqs = [
+        tau ~ str_scale * (exp(-(w_rel / w_st)^2) * w_rel / w_st) +
+              tau_c * tanh(w_rel / w_coul) + f * w_rel, # Stribeck friction + Coulomb friction + Viscous friction
+    ]
+    extend(ODESystem(eqs, t, [], pars; name = name), partial_comp)
+end