Compare revisions

*.jl.cov

*.jl.cov

*.jl.*.cov

*.jl.*.cov

*.jl.mem

*.jl.mem

docs/build/

docs/site/

docs/.documenter

# This file is a template, and might need editing before it works on your project.

# An example .gitlab-ci.yml file to test (and optionally report the coverage

# results of) your [Julia][1] packages. Please refer to the [documentation][2]

# for more information about package development in Julia.

# Below is the template to run your tests in Julia

.test_template: &test_definition

  # Uncomment below if you would like to run the tests on specific references

  # only, such as the branches `master`, `development`, etc.

  # only:

  #   - master

  #   - development

  script:

    # Let's run the tests. Substitute `coverage = false` below, if you do not

    # want coverage results.

    - julia -e 'Pkg.rm("LabProcesses");Pkg.clone(pwd()); Pkg.test("LabProcesses",coverage = false)'

    #- julia -e 'Pkg.update();Pkg.test("LabProcesses", coverage = true)'

    # Comment out below if you do not want coverage results.

    #- julia -e 'Pkg.add("Coverage"); cd(Pkg.dir("LabProcesses"));

    #  using Coverage; cl, tl = get_summary(process_folder());

    #  println("(", cl/tl*100, "%) covered")'

# Name a test and select an appropriate image.

test:0.6.0:

  image: julialang/julia:v0.6.0

  <<: *test_definition

# REMARK: Do not forget to enable the coverage feature for your project, if you

# are using code coverage reporting above. This can be done by

#

# - Navigating to the `CI/CD Pipelines` settings of your project,

# - Copying and pasting the default `Simplecov` regex example provided, i.e.,

#   `\(\d+.\d+\%\) covered` in the `test coverage parsing` textfield.

#

# WARNING: This template is using the `julialang/julia` images from [Docker

# Hub][3]. One can use custom Julia images and/or the official ones found

# in the same place. However, care must be taken to correctly locate the binary

# file (`/opt/julia/bin/julia` above), which is usually given on the image's

# description page.

#

# [3]: http://hub.docker.com/

## News

2018-12-07: Updated to julia v1.0, see commit eac09291 for last julia v0.6 version

[![pipeline status](https://gitlab.control.lth.se/processes/LabProcesses.jl/badges/master/pipeline.svg)](https://gitlab.control.lth.se/processes/LabProcesses.jl/commits/master)

[![coverage report](https://gitlab.control.lth.se/processes/LabProcesses.jl/badges/master/coverage.svg)](https://gitlab.control.lth.se/processes/LabProcesses.jl/commits/master)

# LabProcesses

# LabProcesses

This package contains an (programming- as well as connection-) interface to serve

Documentation available at [Documentation](http://processes.gitlab.control.lth.se/documentation/labprocesses/)

as a base for the implementation of lab-process software. The first example of

an implementaiton of this interface is for the ball-and-beam process, which is

used in Lab1 FRTN35: frequency response analysis of the beam. The lab is implemented

# Automatiskt genererad dokumentation

in [BallAndBeam.jl](https://gitlab.control.lth.se/processes/BallAndBeam.jl), a

Det finns i skrivande stund två stycken mer eller mindre automatgenererade hemsidor med dokumentation, en sida till repot BallAndBeam.jl

package that makes use of `LabProcesses.jl` to handle the communication with

    http://processes.gitlab.control.lth.se/documentation/ballandbeam/

the lab process and/or a simulated version thereof. This way, the code written

for frequency response analysis of the beam can be run on another process

och en sida till (detta) repot LabProcesses.jl

implementing the same interface (or a simulated version) by changeing a single

    http://processes.gitlab.control.lth.se/documentation/labprocesses

line of code :)

Mitt förslag är att alla som känner sig ansvariga för ett repo som är skapat med syfte att till slut överlämnas till framtida kollegor sätter upp liknande

dokumentation för detta repo.

## Generera dokumentation

Jag har byggt dokumentationen med [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). Detta verktyg accepterar en markdown-fil (docs/src/index.md)

med lite text man skrivit samt macron som indikerar att man vill infoga docstrings från funktioner och typer i sitt juliapaket.

Outputen är en html-sida med tillbehör som man ska se till att hosta på gitlab pages.

## Installation

Exempel på hur detta går till finns i repona LabProcesses.jl och BallAndBeam.jl. Man kan helt sonika kopiera docs/-mappen från ett av dessa repon och

1. Start julia

modifiera innehållet i alla filer så att det stämmer med ens nya repo.

2. Install LabProcesses.jl using command `Pkg.clone("https://gitlab.control.lth.se/processes/LabProcesses.jl.git")` Lots of packages will now be installed, this will take some time.

## How to implement a new process

## Hosting

1. Locate the file [interface.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface.jl). (Alternatively, you can copy all definitions from [/interface_implementations/ballandbeam.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_implementations/ballandbeam.jl) instead. Maybe it's easier to work from an existing implementaiton.)

För hosting finns repot

2. Copy all function definitions.

https://gitlab.control.lth.se/processes/documentation/

3. Create a new file under `/interface_implementations` where you paste all the

Det man behöver göra är att editera filen

copied definitions and implement them. See [/interface_implementations/ballandbeam.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_implementations/ballandbeam.jl) for an example.

https://gitlab.control.lth.se/processes/documentation/blob/master/.gitlab-ci.yml

4. Above all function implementations you must define the process type, e.g,

och lägga till tre rader som

    ```julia

    struct BallAndBeam <: PhysicalProcess

        h::Float64

    end

    BallAndBeam() = BallAndBeam(0.01) # Constructor with default value of sample time

    ```

Make sure you inherit from `PhysicalProcess` or `SimulatedProcess` as appropriate.

5. Documentation of all interface functions is available in the file [interface_documentation.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_documentation.jl)

## Control a process

- Bygger dokumentationen i repot man vill dokumentera

The interface `AbstractProcess` defines the functions `control(P, u)` and `measure(P)`.

- skapar en ny mapp med ett väl valt namn (myfoldername i exemplet nedan)

These functions can be used to implement your own control loops. A common loop

- flyttar den byggda dokumentationen till den mappen

with a feedback controller and a feedforward filter on the reference is implemented

- Det blir lätt att förstå hur man gör punkterna ovan när man kollar i filen .gitlab-ci.yml, bara kör mönstermatchning mot de repona som detta redan är gjort för.

in the function [`run_control_2DOF`](@ref).

The macro `@periodically` might come in handy if you want to implement your own loop.

När .gitlab-ci.yml uppdateras i master triggas en pipline. Om denna lyckas kommer dokumentationen finnas under

Consider the following example, in which the loop body will be run periodically

with a sample time of `h` seconds.

```julia

for (i,t) = enumerate(0:h:duration)

    @periodically h begin

        y[i] = measure(P)

        r[i] = reference(t)

        u[i] = control(i)

        control(P, u[i])

    end

end

```

Often one finds the need to implement a stateful controller, i.e., a function

http://processes.gitlab.control.lth.se/documentation/myfoldername/

that has a memory or state. To this end, the function [`sysfilter`](@ref) is

provided. This function is used to implement control loops where a signal is

filtered through a dynamical system, i.e., `U(z) = C(z)E(z)`.

Usage is demonstrated below

```julia

stateC = init_sysfilter(C)

function control(i)

    e = r[i]-y[i]

    u = sysfilter!(stateC, C, e)

end

```

`C` must here be represented by a [`StateSpace`](http://juliacontrol.github.io/ControlSystems.jl/latest/lib/constructors/#ControlSystems.ss) type from [`ControlSystems.jl`](https://github.com/JuliaControl/ControlSystems.jl).

`TransferFunction` types can easily be converted to a `StateSpace` by `Gss = ss(Gtf)`.

julia 0.6

julia 0.7

ControlSystems

ControlSystems

Parameters

DSP

using Documenter, LabProcesses

# makedocs()

# deploydocs(

# deps   = Deps.pip("pygments", "mkdocs", "python-markdown-math", "mkdocs-cinder"),

# repo   = "gitlab.control.lth.se/processes/LabProcesses.jl",

# branch = "gh-pages",

# julia  = "0.6",

# osname = "linux"

# )

makedocs(

    format = :html,

    sitename = "LabProcesses",

    pages = [

        "index.md",

    ]

)

site_name:        LabProcesses.jl

repo_url:         https://gitlab.control.lth.se/labdev/software/tree/master/julia_ballandbeam/LabProcesses.jl

site_description: Documentation for LabProcesses.jl

site_author:      Fredri Bagge Carlson

theme: cinder

extra_css:

  - assets/Documenter.css

extra_javascript:

  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML

  - assets/mathjaxhelper.js

markdown_extensions:

  - extra

  - tables

  - fenced_code

  - mdx_math:

      enable_dollar_delimiter: True

docs_dir: 'build'

pages:

  - Home: index.md

# LabProcesses

```@contents

Depth = 3

```

This package contains an (programming- as well as connection-) interface to serve

as a base for the implementation of lab-process software. The first example of

an implementaiton of this interface is for the ball-and-beam process, which is

used in Lab1 FRTN35: frequency response analysis of the beam. The lab is implemented

in [BallAndBeam.jl](https://gitlab.control.lth.se/processes/BallAndBeam.jl), a

package that makes use of `LabProcesses.jl` to handle the communication with

the lab process and/or a simulated version thereof. This way, the code written

for frequency response analysis of the beam can be run on another process

implementing the same interface (or a simulated version) by changeing a single

line of code :)

## Installation

1. Start julia by typing `julia` in a terminal, make sure the printed info says it's

`v0.6+` running. If not, visit [julialang.org](https://julialang.org/downloads/)

to get the latest release.

2. Install LabProcesses.jl using command `Pkg.clone("https://gitlab.control.lth.se/processes/LabProcesses.jl.git")` Lots of packages will now be installed, this will take some time. If this is your first time using Julia, you might have to run `julia> Pkg.init()` before you install any packages.

# How to implement a new process

### 1.

Locate the file [interface.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface.jl). When the package is installed, you find its directory under `~/.julia/v0.6/LabProcesses/`, if not, run `julia> Pkg.dir("LabProcesses")` to locate the directory.

(Alternatively, you can copy all definitions from [/interface_implementations/ballandbeam.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_implementations/ballandbeam.jl) instead. Maybe it's easier to work from an existing implementaiton.)

### 2.

Copy all function definitions.

### 3.

Create a new file under `/interface_implementations` where you paste all the

copied definitions and implement them. See [/interface_implementations/ballandbeam.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_implementations/ballandbeam.jl) for an example.

### 4.

Above all function implementations you must define the process type, e.g,

```julia

struct BallAndBeam <: PhysicalProcess

    h::Float64

    bias::Float64

end

BallAndBeam() = BallAndBeam(0.01, 0.0) # Constructor with default value of sample time

```

Make sure you inherit from `PhysicalProcess` or `SimulatedProcess` as appropriate.

This type must contains fields that hold information about everything that is

relevant to a particular instance of the process. Different ballandbeam-process

have different biases, hence this must be stored. A simulated process would have

to keep track of its state etc. in order to implement the measure and control

methods. See [Types in julia documentation](https://docs.julialang.org/en/stable/manual/types/#Composite-Types-1)

for additional info regarding user defined types and (constructors)[https://docs.julialang.org/en/stable/manual/constructors/].

### 5.

Documentation of all interface functions is available in the file [interface_documentation.jl](https://gitlab.control.lth.se/processes/LabProcesses.jl/blob/master/src/interface_documentation.jl)

# How to control a process

The interface `AbstractProcess` defines the functions `control(P, u)` and `measure(P)`.

These functions can be used to implement your own control loops. A common loop

with a feedback controller and a feedforward filter on the reference is implemented

in the function [`run_control_2DOF`](@ref), where the user can supply $G_1$ and $G_4$

in the diagram below, with the process $P=G_2$.

![block diagram](feedback4.png)

The macro `@periodically` might come in handy if you want to implement your own loop.

Consider the following example, in which the loop body will be run periodically

with a sample time of `h` seconds.

```julia

for (i,t) = enumerate(0:h:duration)

    @periodically h begin

        y[i] = measure(P)

        r[i] = reference(t)

        u[i] = calc_control(y,r)

        control(P, u[i])

    end

end

```

Often one finds the need to implement a stateful controller, i.e., a function

that has a memory or state. To this end, the type [`SysFilter`](@ref) is

provided. This type is used to implement control loops where a signal is

filtered through a dynamical system, i.e., `U(z) = G1(z)E(z)`.

Usage is demonstrated below, which is a simplified implementation of the block

diagram above (transfer function- and signal names corresponds to the figure).

First two `SysFilter` objects are created, these objects can now be used as

functions of an input, and return the filtered output. The `SysFilter` type takes

care of updating and remembering the state of the system when called.

```julia

G1f = SysFilter(G1)

G4f = SysFilter(G4)

function calc_control(y,r)

    rf = G4f(r)

    e  = rf-y

    u  = G1f(e)

end

```

`G1` and `G4` must here be represented by [`StateSpace`](http://juliacontrol.github.io/ControlSystems.jl/latest/lib/constructors/#ControlSystems.ss) types

from [`ControlSystems.jl`](https://github.com/JuliaControl/ControlSystems.jl), e.g., `G1 = ss(A,B,C,D)`.

`TransferFunction` types can easily be converted to a `StateSpace` by `Gss = ss(Gtf)`.

Continuous time systems can be discretized using `Gd = c2d(Gc, h)[1]`. (The sample time of a process is available through `h = sampletime(P)`.)

# How to implement a Simulated Process

## Linear process

This is very easy, just get a discrete time `StateSpace` model of your process

(if you have a transfer function, `Gss = ss(Gtf)` will do the trick, if you have continuous time, `Gd = c2d(Gc,h)[1]` is your friend).

You now have to implement the methods `control` and `measure` for your simulated type.

The implementation for `BeamSimulator` is shown below

```julia

control(p::BeamSimulator, u) = p.Gf(u)

measure(P) = vecdot(p.Gf.sys.C, p.Gf.state)

```

The `control` method accepts a control signal (`u`) and propagates the system state

(`p.Gf.state`) forward using the statespace model (`p.Gf.sys`) of the beam. The object

`Gf` (of type [`SysFilter`](@ref)) is familiar from the "Control" section above. What it does

is essentially (simplified)

```julia

function Gf(input)

    sys       = Gf.sys

    Gf.state .= sys.A*Gf.state + sys.B*input

    output    = sys.C*Gf.state + sys.D*input

end

```

hence, it just performs one iteration of

```math

x' = Ax + Bu

```

```math

y  = Cx + Du

```

The `measure` method performs the computation `y = Cx`, the reason for the call

to `vecdot` is that `vecdot` produces a scalar output, whereas `C*x` produces a

1-element `Matrix`. A scalar output is preferred in this case since the `Beam`

is SISO.

It should now be obvious which fields are required in the `BeamSimulator` type.

It must know which sample time it has been discretized with, as well as its

discrete-time system model. It must also remember the current state of the system.

This is not needed in a physical process since it kind of remembers its own state.

The system model and its state is conveniently covered by the type [`SysFilter`](@ref),

which handles filtering of a signal through an LTI system.

The full type specification for `BeamSimulator` is given below

```julia

struct BeamSimulator <: SimulatedProcess

    h::Float64

    Gf::SysFilter

    BeamSimulator() = new(0.01, SysFilter(beam_system, 0.01))

    BeamSimulator(h::Real) = new(Float64(h), SysFilter(beam_system, h))

end

```

It contains three fields and two inner constructors. The constructors initializes

the system filter by creating a [`SysFilter`](@ref).

The variable `beam_system` is already defined outside the type specification.

One of the constructors provides a default value for the sample time, in case

the user is unsure about a reasonable value.

## Non-linear process

Your first option is to linearize the process and proceed like above.

Other options include

1. Make `control` perform forward Euler, i.e., `x[t+1] = x[t] + f(x[t],u[t])*h` for a general system model ``x' = f(x,u); y = g(x,u)`` and sample time ``h``.

2. Integrate the system model using some fancy method like Runge-Kutta. See [DifferentialEquations.jl](http://docs.juliadiffeq.org/stable/types/discrete_types.html) for discrete-time solving of ODEs (don't be discouraged, this is almost as simple as forward Euler above).

# Exported functions and types

```@autodocs

Modules = [LabProcesses]

Private = false

Pages   = ["LabProcesses.jl", "controllers.jl", "reference_generators.jl", "utilities.jl"]

```

# Process interface specification

All processes must implement the following interface. See the existing

implementations in the folder `interface_implementations` for guidance.

```@autodocs

Modules = [LabProcesses]

Private = false

Pages   = ["interface_documentation.jl"]

```

# Index

```@index

```

__precompile__()

# __precompile__()

using Pkg

installed_packages = Pkg.installed()

if "LabConnections" ∉ keys(installed_packages)

	Pkg.clone("https://gitlab.control.lth.se/cont-frb/LabConnections.jl")

	# Pkg.checkout("LabConnection","v0.0.1")

end

module LabProcesses

module LabProcesses

using ControlSystems

using ControlSystems, LabConnections.Computer, Parameters, DSP, LinearAlgebra

include("utilities.jl")

include("interface.jl")

include("interface.jl")

include("interface_documentation.jl")

include("interface_documentation.jl")

include("interface_implementations/ballandbeam.jl")

include("interface_implementations/ballandbeam.jl")

include("interface_implementations/eth_helicopter.jl")

include("utilities.jl")

include("reference_generators.jl")

include("controllers.jl")

include("controllers.jl")

end # module

end # module

export run_control_2DOF

export run_control_2DOF

"""

"""

	y,u,r = run_control(process, sysFB[, sysFF]; duration = 10, reference(t) = sign(sin(2π*t)))

	y,u,r = run_control_2DOF(process, sysFB[, sysFF]; duration = 10, reference(t) = sign(sin(2π*t)))

Perform control experiemnt where the feedback and feedforward controllers are given by

Perform control experiemnt on process where the feedback and feedforward controllers are given by

`sysFB` and `sysFF`, both of type `StateSpace`.

`sysFB` and `sysFF`, both of type `StateSpace`.

`reference` is a reference generating function that accepts a scalar `t` (time in seconds) and outputs a scalar `r`, default is `reference(t) = sign(sin(2π*t))`.

`reference` is a reference generating function that accepts a scalar `t` (time in seconds) and outputs a scalar `r`, default is `reference(t) = sign(sin(2π*t))`.

The outputs `y,u,r` are the beam angle, control signal and reference respectively.

The outputs `y,u,r` are the beam angle, control signal and reference respectively.

![block diagram](feedback4.png)

"""

"""

function run_control_2DOF(P::AbstractProcess,sysFB, sysFF=nothing; duration = 10, reference = t->sign(sin(2π*t)))

function run_control_2DOF(P::AbstractProcess,sysFB, sysFF=nothing; duration = 10, reference = t->sign(sin(2π*t)))

	nu = num_inputs(P)

	ny = num_outputs(P)

	h  = sampletime(P)

	h  = sampletime(P)

	y       = zeros(0:h:duration)

	y  = zeros(ny, length(0:h:duration))

	u       = zeros(0:h:duration)

	u  = zeros(nu, length(0:h:duration))

	r       = zeros(0:h:duration)

	r  = zeros(ny, length(0:h:duration))

	stateFB = init_sysfilter(sysFB)

	Gfb = SysFilter(sysFB)

	if sysFF != nothing

	if sysFF != nothing

		stateFF = init_sysfilter(sysFF)

		Gff = SysFilter(sysFF)

	end

	end

	function calc_control(i)

	function calc_control(i)

		rf = sysFF == nothing ? r[i] : sysfilter!(stateFF, sysFF, r[i])

		rf = sysFF == nothing ? r[:,i] : Gff(r[:,i])

		e  = rf-y[i]

		e  = rf-y[:,i]

		ui = sysfilter!(stateFB, sysFB, e)[1]

		ui = Gfb(e)

		ui + bias(P)

		ui .+ bias(P)

	end

	end

	simulation = isa(P, SimulatedProcess)

	initialize(P)

	initialize(P)

	for (i,t) = enumerate(0:h:duration)

	for (i,t) = enumerate(0:h:duration)

		@periodically h begin

		@periodically h simulation begin

			y[i]       = measure(P)

			y[:,i]    .= measure(P)

			r[i]       = reference(t)

			r[:,i]    .= reference(t)

			u[i]       = calc_control(i) # y,r must be updated before u

			u[:,i]    .= calc_control(i) # y,r must be updated before u

			control(P, u[i])

			control(P, [clamp.(u[j,i], inputrange(P)[j]...) for j=1:nu])

		end

		end

	end

	end

	finalize(P)

	finalize(P)

	y,u,r

	y',u',r'

end

end

        isstable,

        isstable,

        isasstable,

        isasstable,

        sampletime,

        sampletime,

        bias,

        control,

        control,

        measure,

        measure,

        initialize,

        initialize,

# Interface implementation Ball And Beam ====================================================

# Interface implementation Ball And Beam ====================================================

export BallAndBeam, BallAndBeamSimulator, BallAndBeamType

# The ball and beam can be used in two modes, either just the Beam, in which case there is a

# single output (measurement signal) or the BallAndBeam, in which case there are two.

# There are a few union types defined for convenience, these are

# AbstractBeam = Union{Beam, BeamSimulator}

# AbstractBallAndBeam   = Union{BallAndBeam, BallAndBeamSimulator}

# AbstractBeamOrBallAndBeam = All types

# Although not Abstract per se, the names AbstractBeam etc. were chosen since this reflects

# their usage in dispatch.

export Beam, BeamSimulator, AbstractBeam, BallAndBeam, BallAndBeamSimulator, AbstractBeamOrBallAndBeam

# @with_kw allows specification of default values for fields. If none is given, this value must be supplied by the user. replaces many constructors that would otherwise only supply default values.

# Call constructor like Beam(bias=1.0) if you want a non-default value for bias

"""

    Beam(;kwargs...)

Physical beam process

#Arguments (fields)

- `h::Float64 = 0.01`

- `bias::Float64 = 0.0`

- `stream::LabStream = ComediStream()`

- `measure::AnalogInput10V = AnalogInput10V(0)`

- `control::AnalogOutput10V = AnalogOutput10V(1)`

"""

struct Beam <: PhysicalProcess

    h::Float64

    bias::Float64

    stream::LabStream

    measure::AnalogInput10V

    control::AnalogOutput10V

end

function Beam(;

    h::Float64               = 0.01,

    bias::Float64            = 0.,

    stream::LabStream        = ComediStream(),

    measure::AnalogInput10V  = AnalogInput10V(0),

    control::AnalogOutput10V = AnalogOutput10V(1))

    p = Beam(Float64(h),Float64(bias),stream,measure,control)

    init_devices!(p.stream, p.measure, p.control)

    p

end

include("define_beam_system.jl")

const beam_system, nice_beam_controller = define_beam_system()

# nice_beam_controller gives ϕₘ=56°, Aₘ=4, Mₛ = 1.6. Don't forget to discretize it before use

struct BeamSimulator <: SimulatedProcess

    h::Float64

    s::SysFilter

    BeamSimulator(;h::Real = 0.01, bias=0) = new(Float64(h), SysFilter(beam_system, h))

end

struct BallAndBeam <: PhysicalProcess

struct BallAndBeam <: PhysicalProcess

    h::Float64

    h::Float64

    bias::Float64

    bias::Float64

    stream::LabStream

    measure1::AnalogInput10V

    measure2::AnalogInput10V

    control::AnalogOutput10V

end

function BallAndBeam(;

    h                        = 0.01,

    bias                     = 0.,

    stream                   = ComediStream(),

    measure1::AnalogInput10V = AnalogInput10V(0),

    measure2::AnalogInput10V = AnalogInput10V(1),

    control::AnalogOutput10V = AnalogOutput10V(1))

    p = BallAndBeam(h,bias,stream,measure1,measure2,control)

    init_devices!(p.stream, p.measure1, p.measure2, p.control)

    p

end

end

BallAndBeam() = BallAndBeam(0.01, 0.0)