DiscreteSystem

Construction of DiscreteSystem

DiscreteSystems evolve by the following discrete time difference equation.

where $x_k$ is the state, $y_k$ is the value of output and $u_k$ is the value of input at discrete time t. $f$ is the state function and $g$ is the output function of the system. See the main constructor.

Basic Construction of DiscreteSystem

When a DiscreteSystem is triggered from its trigger link, it reads current time from its trigger link, reads its input, solves its difference equation, computes its output and writes its output value to its output bus. Let us continue with an example.

We first define state function sfunc and output function ofunc of the system,

julia> using Causal # hide

julia> sfunc(dx, x, u, t) = (dx .= -0.5x)
sfunc (generic function with 1 method)

julia> ofunc(x, u, t) = x
ofunc (generic function with 1 method)

From sfunc, it is seen that the system does not have any input, and from ofunc the system has one output. Thus, the input and output of the system is

julia> input = nothing

julia> output = Outport(1)
1-element Outport{Outpin{Float64}}:
 Outpin(eltype:Float64, isbound:false)

We also need to specify the initial condition and time of the system

julia> x0  = [1.]
1-element Array{Float64,1}:
 1.0

julia> t = 0.
0.0

We are now ready to construct the system ds.

julia> ds = DiscreteSystem(righthandside=sfunc, readout=ofunc, state=x0, input=input, output=output)
DiscreteSystem(righthandside:sfunc, readout:ofunc, state:[1.0], t:0.0, input:nothing, output:Outport(numpins:1, eltype:Outpin{Float64}))

To drive ds, we need to launch it.

julia> iport, trg, hnd = Inport(1), Outpin(), Inpin{Bool}()
(Inport(numpins:1, eltype:Inpin{Float64}), Outpin(eltype:Float64, isbound:false), Inpin(eltype:Bool, isbound:false))

julia> connect!(ds.output, iport)
1-element Array{Link{Float64},1}:
 Link(state:open, eltype:Float64, isreadable:false, iswritable:false)

julia> connect!(trg, ds.trigger)
Link(state:open, eltype:Float64, isreadable:false, iswritable:false)

julia> connect!(ds.handshake, hnd)
Link(state:open, eltype:Bool, isreadable:false, iswritable:false)

julia> task = launch(ds)
Task (runnable) @0x00007fe0da9ab340

julia> task2 = @async while true
           all(take!(iport) .=== NaN) && break
           end
Task (runnable) @0x00007fe0d4438760

At this point, ds is ready to be driven. To drive ds, we can either use drive(ds, t) or put!(ds.trigger, t).

julia> put!(trg, 1.)

When the above code is executed, ds evolves until its time is ds.t is 1., During this evolution, ds reads time t from its trigger link, reads its input (in this example, ds has no input, so it does nothing when reading its input), solves its difference equation, computes its output and writes its output value to its output. To signal that the evolution is succeeded, ds writes true its handshake link which needs to be taken to further drive ds.

julia> hnd.link  # `handshake` link is readable
Link(state:open, eltype:Bool, isreadable:true, iswritable:false)

julia> take!(hnd)
true

We continue to drive ds,

julia> for i in 2. : 10.
           put!(trg, i)
           take!(hnd)
       end

Note that all the output values of ds is written to its output bus.

julia> iport[1].link.buffer
64-element Buffer{Cyclic,Float64,1}:
  0.0009765625
 -0.001953125
  0.00390625
 -0.0078125
  0.015625
 -0.03125
  0.0625
 -0.125
  0.25
 -0.5
  ⋮
  0.0
  0.0
  0.0
  0.0
  0.0
  0.0
  0.0
  0.0
  0.0

When we launched ds, we constructed a task which is still running.

julia> task
Task (runnable) @0x00007fe0da9ab340

julia> task2
Task (runnable) @0x00007fe0d4438760

As long nothing goes wrong, i.e. no exception is thrown, during the evolution of ds, it is possible to drive ds. To safely terminate the task, we need to terminate the ds.

julia> put!(trg, NaN)

julia> put!(ds.output, [NaN])
1-element Array{Float64,1}:
 NaN

We can confirm that the task is not running and its state is done.

julia> task
Task (done) @0x00007fe0da9ab340

julia> task2
Task (done) @0x00007fe0d4438760

Since the task is not running any more, ds cannot be drivable any more. However to drive ds again, we need launch ds again.

Full API

@def_discrete_system ex

@def_discrete_system mutable struct MyDiscreteSystem{T1,T2,T3,...,TN,OP,RH,RO,ST,IP,OP} <: AbstractDiscreteSystem
    param1::T1 = param1_default                 # optional field 
    param2::T2 = param2_default                 # optional field 
    param3::T3 = param3_default                 # optional field
        ⋮
    paramN::TN = paramN_default                 # optional field 
    righthandside::RH = righthandside_function  # mandatory field
    readout::RO = readout_function              # mandatory field
    state::ST = state_default                   # mandatory field
    input::IP = input_default                   # mandatory field
    output::OP = output_default                 # mandatory field 
end

function righthandside(dx, x, u, t, args...; kwargs...)
    dx .= .... # update dx 
end

function readout(x, u, t)
    y = ...
    return y
end

julia> @def_discrete_system mutable struct MyDiscreteSystem{RH, RO, IP, OP} <: AbstractDiscreteSystem 
       α::Float64 = 1. 
       β::Float64 = 2. 
       righthandside::RH = (dx, x, u, t, α=α) -> (dx[1] = α * x[1] + u[1](t))
       state::Vector{Float64} = [1.]
       readout::RO = (x, u, t) -> x
       input::IP = Inport(1) 
       output::OP = Outport(1) 
       end

julia> ds = MyDiscreteSystem();

julia> ds.input 
1-element Inport{Inpin{Float64}}:
 Inpin(eltype:Float64, isbound:false)

DiscreteSystem(; righthandside, readout, state, input, output)

julia> sfuncdiscrete(dx,x,u,t) = (dx .= 0.5x);

julia> ofuncdiscrete(x, u, t) = x;

julia> DiscreteSystem(righthandside=sfuncdiscrete, readout=ofuncdiscrete, state=[1.], input=nothing, output=Outport())
DiscreteSystem(righthandside:sfuncdiscrete, readout:ofuncdiscrete, state:[1.0], t:0.0, input:nothing, output:Outport(numpins:1, eltype:Outpin{Float64}))

DiscreteLinearSystem(input, output, modelargs=(), solverargs=(); 
    A=fill(-1, 1, 1), B=fill(0, 1, 1), C=fill(1, 1, 1), D=fill(0, 1, 1), state=rand(size(A,1)), t=0., 
    alg=ODEAlg, modelkwargs=NamedTuple(), solverkwargs=NamedTuple())

Henon()

LoziSystem()

BogdanovSystem()

GingerbreadmanSystem()

LogisticSystem()