Compare revisions

*.jl.cov

*.jl.*.cov

*.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

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

# Automatiskt genererad dokumentation

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

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

och en sida till (detta) repot LabProcesses.jl

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

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.

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

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

## Hosting

För hosting finns repot

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

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

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

och lägga till tre rader som

- Bygger dokumentationen i repot man vill dokumentera

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

- flyttar den byggda dokumentationen till den mappen

- 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.

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

Under development /Bagge

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

julia 0.6

julia 0.7

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

```

module LabProcesses

# Interface specification ===================================================================

abstract type AbstractProcess end

abstract type PhycicalProcess  <: AbstractProcess end

abstract type SimulatedProcess <: AbstractProcess end

num_outputs(p::AbstractProcess) = p.ny

num_inputs(p::AbstractProcess)  = p.nu

outputrange(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")

inputrange(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

isstable(p::AbstractProcess)    = error("Function not implemented for $(typeof(p))")

sampletime(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

control(p::AbstractProcess, u)  = error("Function not implemented for $(typeof(p))")

measure(p::AbstractProcess)     = error("Function not implemented for $(typeof(p))")

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

struct BallAndBeam <: PhysicalProcess

    h::Float64

# __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

struct BallAndBeamSimulator <: SimulatedProcess

    h::Float64

end

const BallAndBeamType = Union{BallAndBeam, BallAndBeamSimulator}

num_outputs(p::BallAndBeamType) = 2

num_inputs(p::BallAndBeamType)  = 1

outputrange(p::BallAndBeamType) = [(-10,10)]

inputrange(p::BallAndBeamType)  = [(-10,10)]

isstable(p::BallAndBeamType)    = false

sampletime(p::BallAndBeamType)  = p.h

module LabProcesses

control(p::BallAndBeam, u)  = ccall((:comedi_write, comedipath),Int32,

                                        (Int32,Int32,Int32,Int32),0,1,1,num2io(u[1]))

measure(p::BallAndBeam)     = io2num(ccall((:comedi_read,comedipath), Int32,

                                        (Int32,Int32,Int32), 0,0,0))

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

const comedipath = "../c/comedi_bridge.so"

const conversion = 65535/20

io2num(x) = x/conversion -10            # Converts from io to float

num2io(x) = round(Int32,x*100 + 2050)   # Converts from regular number to io

include("utilities.jl")

control(p::BallAndBeamSimulator, u)  = error("Not yet implemented")

measure(p::BallAndBeamSimulator)     = error("Not yet implemented")

include("interface.jl")

include("interface_documentation.jl")

include("interface_implementations/ballandbeam.jl")

include("interface_implementations/eth_helicopter.jl")

include("reference_generators.jl")

include("controllers.jl")

end # module

export run_control_2DOF

"""

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

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

`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))`.

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)))

	nu = num_inputs(P)

	ny = num_outputs(P)

	h  = sampletime(P)

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

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

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

	Gfb = SysFilter(sysFB)

	if sysFF != nothing

		Gff = SysFilter(sysFF)

	end

	function calc_control(i)

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

		e  = rf-y[:,i]

		ui = Gfb(e)

		ui .+ bias(P)

	end

	simulation = isa(P, SimulatedProcess)

	initialize(P)

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

		@periodically h simulation begin

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

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

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

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

		end

	end

	finalize(P)

	y',u',r'

end

export AbstractProcess, PhysicalProcess, SimulatedProcess

export  num_outputs,

        num_inputs,

        outputrange,

        inputrange,

        isstable,

        isasstable,

        sampletime,

        bias,

        control,

        measure,

        initialize,

        finalize

# Interface specification ===================================================================

abstract type AbstractProcess end

abstract type PhysicalProcess  <: AbstractProcess end

abstract type SimulatedProcess <: AbstractProcess end

## Function definitions =====================================================================

num_outputs(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")

num_inputs(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

outputrange(p::AbstractProcess) = error("Function not implemented for $(typeof(p))")

inputrange(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

isstable(p::AbstractProcess)    = error("Function not implemented for $(typeof(p))")

isasstable(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

sampletime(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

bias(p::AbstractProcess)        = error("Function not implemented for $(typeof(p))")

control(p::AbstractProcess, u)  = error("Function not implemented for $(typeof(p))")

measure(p::AbstractProcess)     = error("Function not implemented for $(typeof(p))")

initialize(p::AbstractProcess)  = error("Function not implemented for $(typeof(p))")

finalize(p::AbstractProcess)    = error("Function not implemented for $(typeof(p))")

# This file contains all the docstrings so that the interface specification file is not cluttered

"""

    AbstractProcess

Base abstract type for all lab processes. This should not be inherited from directly, see [`PhysicalProcess`](@ref), [`SimulatedProcess`](@ref)

"""

AbstractProcess

"""

    PhysicalProcess <: AbstractProcess

Pysical processes should inherit from this abstract type.

"""

PhysicalProcess

"""

    SimulatedProcess <: AbstractProcess

Simulated processes should inherit from this abstract type.

"""

SimulatedProcess

"""

    ny = num_outputs(P::AbstractProcess)

Return the number of outputs (measurement signals) of the process.

"""

num_outputs

"""

    nu = num_inputs(P::AbstractProcess)

Return the number of inputs (control signals) of the process.

"""

num_inputs

"""

    range = outputrange(P::AbstractProcess)

Return the range of outputs (measurement signals) of the process. `range` is a vector of

tuples,  `length(range) = num_outputs(P), eltype(range) = Tuple(Real, Real)`

"""

outputrange

"""

    range = inputrange(P::AbstractProcess)

Return the range of inputs (control signals) of the process. `range` is a vector of

tuples,  `length(range) = num_inputs(P), eltype(range) = Tuple(Real, Real)`

"""

inputrange

"""

    isstable(P::AbstractProcess)

Return true/false indicating whether or not the process is stable

"""

isstable

"""

    isasstable(P::AbstractProcess)

Return true/false indicating whether or not the process is asymptotically stable

"""

isasstable

"""

    h = sampletime(P::AbstractProcess)

Return the sample time of the process in seconds.

"""

sampletime

"""

    b = bias(P::AbstractProcess)

Return an input bias for the process. This could be, i.e., the constant input u₀ around which

a nonlinear system is linearized, or whatever other bias might exist on the input.

`length(b) = num_inputs(P)`

"""

bias

"""

    control(P::AbstractProcess, u)

Send a control signal to the process. `u` must have dimension equal to `num_inputs(P)`

"""

control

"""

    y = measure(P::AbstractProcess)

Return a measurement from the process. `y` has length `num_outputs(P)`

"""

measure

"""

    initialize(P::AbstractProcess)

This function is called before any control or measurement operations are performed. During a call to `initialize`, one might set up external communications etc. After control is done,

the function [`finalize`](@ref) is called.

"""

initialize

"""

    finalize(P::AbstractProcess)

This function is called after any control or measurement operations are performed. During a call to `finalize`, one might finalize external communications etc. Before control is done,

the function [`initialize`](@ref) is called.

"""

finalize

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

# 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)`