Signals

The functions below operate on signals.

Note

SignalTables.jl exports all symbols of this table.
Modia.jl reexports all symbols.

Signal functions	Description
`Var`	Returns a variable signal definition in form of a dictionary.
`Par`	Returns a parameter signal definition in form of a dictionary.
`Map`	Returns an attribute signal definition in form of a dictionary.
`isVar`	Returns true, if signal is a `Var`.
`isPar`	Returns true, if signal is a `Par`.
`isMap`	Returns true, if signal is a `Map`.
`isSignal`	Returns true, if signal is a `Var`, `Par` or `Map`.
`showSignal`	Prints a `Var`, `Par` or `Map` signal to io.
`eltypeOrType`	Returns eltype of an array (but without Missing) and otherwise returns typeof.
`quantity`	Returns `Unitful.Quantity` from numberType and numberUnit, e.g. `quantity(Float64,u"m/s")`
`unitAsParseableString`	Returns the unit as a String that can be parsed with `Unitful.uparse`, e.g. "m*s^-1"

SignalTables.Var — Function

signal = Var(; kwargs...)::OrderedDict{Symbol,Any}

Returns a variable signal definition in form of a dictionary. kwargs... are key/value pairs of variable attributes.

The :values key represents a signal array of any element type as function of the independent signal(s) (or is the k-th independent variable). A signal array has indices [i1,i2,...,j1,j2,...] to hold variable elements [j1,j2,...] at the [i1,i2,...] independent signal(s). If an element of a signal array is not defined it has a value of missing. Furthermore, additional attributes can be stored.

The following keys are recognized (all are optional with exception of :values that must be either directly defined or via :alias):

key	value (of type String, if not obvious from context)
`:values`	Array{T,N}: `signal[:values][i1,i2,...j1,j2,...]` is value `[j1,j2,...]` at the `[i1,i2,...]` independent signal(s), or `signal[:values][i_k]` is value `[i_k]` of the k-th independent variable.
`:unit`	String: Unit of all signal elements (parseable with `Unitful.uparse`), e.g., `"kgms^2"`. Array{String,N}: `signal[:unit][j1,j2,...]` is unit of variable element `[j1,j2,...]`.
`:info`	Short description of signal (= `description` of FMI 3.0 and of Modelica).
`:independent`	= true, if independent variable (k-th independent variable is k-th Var insignal table)
`:variability`	`"continuous", "clocked", "clock", "discrete",` or `"tunable"` (parameter).
`:state`	= true, if signal is a (continuous, clocked, or discrete) state.
`:der`	String: `getSignal(signalTable, signal[:der])[:values]` is the derivative of `signal[:values]`.
`:clock`	String: `getSignal(signalTable, signal[:clock])[:values]` is the clock associated with `signal[:values]` (is only defined at clock ticks and otherwise is missing). If `Vector{String}`, a set of clocks is associated with the signal.
`:alias`	String: `signal[:values]` is a reference to `getSignal(signalTable, signal[:alias])[:values]`. The reference is set and attributes are merged when the Var-signal is added to the signal table.
`:interpolation`	Interpolation of signal points (`"linear", "none"`). If not provided, `interpolation` is deduced from `:variability` and otherwise interpolation is `"linear".
`:extrapolation`	Extrapolation outside the values of the independent signal (`"none"`).

Additionally, any other signal attributes can be stored in signal with a desired key, such as Variable Types of FMI 3.0.

Example

using SignalTables

t = (0.0:0.1:0.5)
t_sig = Var(values = t, unit=u"s",  independent=true)
w_sig = Var(values = sin.(t), unit="rad/s", info="Motor angular velocity")
c_sig = Var(values = [1.0, missing, missing, 4.0, missing, missing],
            variability="clocked")
b_sig = Var(values = [false, true, true, false, false, true])
a_sig = Var(alias = "w_sig")

source

SignalTables.Par — Function

signal = Par(; kwargs...)::OrderedDict{Symbol,Any}

Returns a parameter signal definition in form of a dictionary. A parameter is a variable that is constant and is not a function of the independent variables. kwargs... are key/value pairs of parameter attributes.

The value of a parameter variable is stored with key :value in signal and is an instance of any Julia type (number, string, array, tuple, dictionary, ...).

The following keys are recognized (all are optional):

key	value (of type String, if not obvious from context)
`:value`	`signal[:value]` is a constant value that holds for all values of the independent signals.
`:unit`	String: Unit of all signal elements (parseable with `Unitful.uparse`), e.g., `"kgms^2"`. Array{String,N}: `signal[:unit][j1,j2,...]` is unit of variable element `[j1,j2,...]`.
`:info`	Short description of signal (= `description` of FMI 3.0 and of Modelica).
`:alias`	String: `signal[:value]` is a reference to `getSignal(signalTable, signal[:alias])[:value]`. The reference is set and attributes are merged when the Par-signal is added to the signal table.

Additionally, any other signal attributes can be stored in signal with a desired key, such as Variable Types of FMI 3.0.

Example

using SignalTables

J         = Par(value = 0.02, unit=u"kg*m/s^2", info="Motor inertia")
fileNames = Par(value = ["data1.json", "data2.json"])
J_alias   = Par(alias = "J")

source

SignalTables.Map — Function

signal = Map(; kwargs...)::OrderedDict{Symbol,Any}

Returns a set of key/value pairs in form of a dictionary. A Map is used to associate a set of attributes to a Variable, Parameter or Signal Table.

The following keys are recognized (all are optional):

key	value
`:info`	Short description.

Additionally, any other signal attributes can be stored in signal with a desired key,

Example

using SignalTables

sigTable = SignalTable(
   J = Par(value = 0.02),
   attributes = Map(author = "xyz")
)

source

SignalTables.isVar — Function

isVar(signal)

Returns true, if signal is a Var.

source

SignalTables.isPar — Function

isPar(signal)

Returns true, if signal is a Par.

source

SignalTables.isMap — Function

isMap(signal)

Returns true, if signal is a Map.

source

SignalTables.isSignal — Function

isSignal(signal)

Returns true, if signal is a Var or a Par or a Map

source

SignalTables.showSignal — Function

showSignal([io=stdout,] signal)

Prints a Var(...) or Par(...) signal to io.

source

SignalTables.eltypeOrType — Function

eltypeOrType(obj)

Returns eltype(obj), if obj is an AbstractArray and otherwise returns typeof(obj).

source

SignalTables.quantity — Function

quantityType = quantity(numberType, numberUnit::Unitful.FreeUnits)

Returns Quantity from numberType and numberUnit, e.g. quantity(Float64,u"m/s")

Example

using SignalTables
using Unitful

mutable struct Data{FloatType <: AbstractFloat}
    velocity::quantity(FloatType, u"m/s")
end

v = Data{Float64}(2.0u"mm/s")
@show v  # v = Data{Float64}(0.002 m s^-1)

sig = Vector{Union{Missing,quantity(Float64,u"m/s")}}(missing,3)
append!(sig, [1.0, 2.0, 3.0]u"m/s")
append!(sig, fill(missing, 2))
@show sig    # [missing, missing, missing, 1.0u"m/s", 2.0u"m/s", 3.0u"m/s", missing, missing]

source

SignalTables.unitAsParseableString — Function

v_unit = unitAsParseableString(v::[Number|AbstractArray])::String

Returns the unit of v as a string that can be parsed with Unitful.uparse.

This allows, for example, to store a quantity with units into a JSON File and recover it when reading the file. This is not (easily) possible with current Unitful functionality, because string(unit(v)) returns a string that cannot be parse with uparse. In Julia this is an unusual behavior because string(something) typically returns a string representation of something that can be again parsed by Julia. For more details, see Unitful issue 412.

Most likely, unitAsParseableString(..) cannot handle all occuring cases.

Examples

using SignalTables
using Unitful

s = 2.1u"m/s"
v = [1.0, 2.0, 3.0]u"m/s"

s_unit = unitAsParseableString(s)  # ::String
v_unit = unitAsParseableString(v)  # ::String

s_unit2 = uparse(s_unit)  # :: Unitful.FreeUnits{(m, s^-1), ..., nothing}
v_unit2 = uparse(v_unit)  # :: Unitful.FreeUnits{(m, s^-1), ..., nothing}

@show s_unit   # = "m*s^-1"
@show v_unit   # = "m*s^-1"

@show s_unit2  # = "m s^-1"
@show v_unit2  # = "m s^-1"

source