Portability | portable |
---|---|

Stability | experimental |

Maintainer | forsyde-dev@ict.kth.se |

This is the ForSyDe library for continuous time MoC (CT-MoC).
Revision: $Revision: 1.7 $
Id: $Id: CTLib.hs,v 1.7 2007*07*11 08:38:34 axel Exp $
It is still experimental.
Right now there are only constructors `combCT`

, `combCT2`

, `delayCT`

,
`shiftCT`

, `mealyCT`

, `mooreCT`

, `scaleCT`

, `addCT`

, `multCT`

and `absCT`

.

The main idea is to represent continuous time signals as functions
`Real --> a`

with `a`

being a numerical type. This allows us to represent a
continuous time signal without loss of information because no sampling or
ADC is required. The sampling occurs only when a signal is evaluated,
for instance when it is plotted.

Thus, a *signal* is represented as a sequence of functions and intervals. For
instance a signal

s = <(sin,[0,100])>

represents a sinus signal in the interval between 0 and 100. The signal

s2 = <(f1(x)=2x, [0,2]), (f2(x)=3+x,[2,4])>

defines a signal that is defined by function `f1`

in the interval `[0,2]`

and by function `f2`

in the interval `[2,4]`

.

A *process* transforms the incoming functions into outgoing functions.
The approach is described in more detail in the ANDRES deliverable D1.1a.
Here we only briefly comment the main functions and constructors.

- data Num a => SubsigCT a = SubsigCT (Rational -> a, (Rational, Rational))
- timeStep :: Rational
- combCT :: Num a => Rational -> ((Rational -> a) -> Rational -> a) -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- combCT2 :: Num a => Rational -> ((Rational -> a) -> (Rational -> a) -> Rational -> a) -> Signal (SubsigCT a) -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- mooreCT :: (Num b, Num c) => (a -> Rational) -> (a -> (Rational -> b) -> a) -> (a -> Rational -> c) -> a -> Signal (SubsigCT b) -> Signal (SubsigCT c)
- mealyCT :: (Num b, Num c) => (a -> Rational) -> (a -> (Rational -> b) -> a) -> (a -> (Rational -> b) -> Rational -> c) -> a -> Signal (SubsigCT b) -> Signal (SubsigCT c)
- delayCT :: Num a => Rational -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- shiftCT :: Num a => Rational -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- initCT :: Num a => Signal (SubsigCT a) -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- scaleCT :: Num a => a -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- addCT :: Num a => Signal (SubsigCT a) -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- multCT :: Num a => Signal (SubsigCT a) -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- absCT :: (Num a, Ord a) => Signal (SubsigCT a) -> Signal (SubsigCT a)
- takeCT :: Num a => Rational -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- dropCT :: Num a => Rational -> Signal (SubsigCT a) -> Signal (SubsigCT a)
- duration :: Num a => Signal (SubsigCT a) -> Rational
- startTime :: Num a => Signal (SubsigCT a) -> Rational
- sineWave :: Floating a => Rational -> (Rational, Rational) -> Signal (SubsigCT a)
- constCT :: Num a => Rational -> a -> Signal (SubsigCT a)
- zeroCT :: Num a => Rational -> Signal (SubsigCT a)
- data DACMode
- a2dConverter :: Num a => Rational -> Signal (SubsigCT a) -> Signal a
- d2aConverter :: Fractional a => DACMode -> Rational -> Signal a -> Signal (SubsigCT a)
- applyF1 :: (Num a, Num b) => ((Rational -> a) -> Rational -> b) -> Signal (SubsigCT a) -> Signal (SubsigCT b)
- applyF2 :: (Num a, Num b, Num c) => ((Rational -> a) -> (Rational -> b) -> Rational -> c) -> Signal (SubsigCT a) -> Signal (SubsigCT b) -> Signal (SubsigCT c)
- applyG1 :: Num b => (a -> (Rational -> b) -> a) -> a -> Signal (SubsigCT b) -> a
- cutEq :: (Num a, Num b) => Signal (SubsigCT a) -> Signal (SubsigCT b) -> (Signal (SubsigCT a), Signal (SubsigCT b))
- plot :: Num a => Signal (SubsigCT a) -> IO String
- plotCT :: Num a => Rational -> [Signal (SubsigCT a)] -> IO String
- plotCT' :: Num a => Rational -> [(Signal (SubsigCT a), String)] -> IO String
- showParts :: Num a => Signal (SubsigCT a) -> [(Double, Double)]
- vcdGen :: Num a => Rational -> [(Signal (SubsigCT a), String)] -> IO String

# The signal data type

data Num a => SubsigCT a Source

The type of a sub-signal of a continuous signal. It consisits of the function and the interval on which the function is defined. The continuous time signal is then defined as a sequence of SubsigCT elements: Signal SubsigCT

This constant gives the default time step for sampling and plotting. Its value is 10ns.

# Primary process constructors

:: Num a | |

=> Rational | The partitioning of the input signal. In other words this gives the time period which is consumed by the process during each evaluation cycle. |

-> ((Rational -> a) -> Rational -> a) | The function that defines the process behaviour |

-> Signal (SubsigCT a) | The input signal |

-> Signal (SubsigCT a) | The output signal of the process. |

`combCT`

is a process constructor with one input and one output signal.
It instantiates a combinatorial, stateless process.

:: Num a | |

=> Rational | The partitioning of both input signals |

-> ((Rational -> a) -> (Rational -> a) -> Rational -> a) | The function defining the process behaviour. |

-> Signal (SubsigCT a) | The first input signal |

-> Signal (SubsigCT a) | The second input signal |

-> Signal (SubsigCT a) | The output signal of the process |

:: (Num b, Num c) | |

=> (a -> Rational) | The gamma function which defines the partitioning of the input signal. |

-> (a -> (Rational -> b) -> a) | The next state function g |

-> (a -> Rational -> c) | The output encoding function f |

-> a | The initial state |

-> Signal (SubsigCT b) | The input signal |

-> Signal (SubsigCT c) | The output signal |

The state-full constructor `mooreCT`

resembles a Moore machine.

:: (Num b, Num c) | |

=> (a -> Rational) | The gamma function which defines the partitioning of the input signal. |

-> (a -> (Rational -> b) -> a) | The next state function g |

-> (a -> (Rational -> b) -> Rational -> c) | The output encoding function f |

-> a | The initial state |

-> Signal (SubsigCT b) | The input signal |

-> Signal (SubsigCT c) | The output signal |

The state-full constructor `mealyCT`

resembles a Mealy machine.

:: Num a | |

=> Rational | The delay |

-> Signal (SubsigCT a) | The input signal |

-> Signal (SubsigCT a) | The output signal |

`delayCT`

is a delay process which simply delays the
output but does not buffer it. The value at each time t is the same as
for the input signal, after the initial delay.

:: Num a | |

=> Rational | The delay |

-> Signal (SubsigCT a) | The input signal |

-> Signal (SubsigCT a) | The output signal |

`shiftCT`

shifts the shape of the input signal by delay
to the right.

:: Num a | |

=> Signal (SubsigCT a) | The initial signal output first. |

-> Signal (SubsigCT a) | Then this signal is output, but delayed. |

-> Signal (SubsigCT a) | The concatation of the two inputs. |

initCT takes an initial signal, outputs it and then copies its second
input signal, which is delayed by the duration of the initial signal.
The delay is realized by `delayCT`

# Derived process constructors

These constructors instantiate very useful processes. They could be defined in terms of the basic constructors but are typically defined in a more direct way for the sake of efficieny.

:: Num a | |

=> a | The scaling factor |

-> Signal (SubsigCT a) | The input signal |

-> Signal (SubsigCT a) | The output signal of the process |

`scaleCT`

amplifies an input by a constant factor:

:: Num a | |

=> Signal (SubsigCT a) | The first input signal |

-> Signal (SubsigCT a) | The second input signal |

-> Signal (SubsigCT a) | The output signal |

`addCT`

adds two input signals together.

:: Num a | |

=> Signal (SubsigCT a) | The first input signal |

-> Signal (SubsigCT a) | The second input signal |

-> Signal (SubsigCT a) | The output signal |

`multCT`

multiplies two input signals together.

`absCT`

takes the absolute value of a signal.

# Convenient functions and processes

Several helper functions are available to obtain parts of a signal, the duration, the start time of a signal, and to generate a sine wave and constant signals.

:: Floating a | |

=> Rational | The frequency |

-> (Rational, Rational) | The interval of the signal |

-> Signal (SubsigCT a) | The generated signal |

`sineWave`

generates a sinus signal with the given frequency defined
over a given period. The function is defined as `f(x)=sin(2*pi*freq*x)`

.

:: Num a | |

=> Rational | The time duration of the generated signal. |

-> a | The constant value of the signal. |

-> Signal (SubsigCT a) | The resulting signal. |

constCT generates a constant signal for a given time duration.

zeroCT generates a constant 0 signal for the given time duration.

# AD and DA converters

For the digital-analog conversion we have two different possibilities
which is determined by this data type `DACMode`

.

:: Num a | |

=> Rational | Sampling Period |

-> Signal (SubsigCT a) | Input signal (continuous time) |

-> Signal a | Output signal (untimed) |

The process `a2dConverter`

converts a continuous time signal to
an untimed or synchronous signal. The first parameter gives the
sampling period of the converter.

Note, that the process `a2dConverter`

is an ideal component,
i.e. there are no losses due to a limited resolution due to a fixed
number of bits.

:: Fractional a | |

=> DACMode | Mode of conversion |

-> Rational | Duration of input signal |

-> Signal a | Input signal (untimed MoC) |

-> Signal (SubsigCT a) | Output signal (continuous time MoC) |

`d2aConverter`

converts an untimes or synchronous signal into a
continuous time signal.
The process `d2aConverter`

converts a signal of the digital domain
into a continuous time signal. There are two modes, `DAlinear`

,
which makes a smooth transition between adjacent digital values and
`DAhold`

, where the analog value directly follows the digital
value. This means that in `DAhold`

-mode a staircase function
remains a staircase function, while in `DAlinear`

the staircase
function would resemble at least partially a *saw tooth*-curve.

The resolution of the converter is given by the parameter
`timeStep`

.

Note, that the process `d2aConverter`

is an ideal component, i.e. there
are no losses due to a limited resolution due to a fixed number of bits.

# Some helper functions

applyF1 :: (Num a, Num b) => ((Rational -> a) -> Rational -> b) -> Signal (SubsigCT a) -> Signal (SubsigCT b)Source

applyF1 applies a function on a sub-signal, which means the function of the subsignal is transformed to another function:

applyF2 :: (Num a, Num b, Num c) => ((Rational -> a) -> (Rational -> b) -> Rational -> c) -> Signal (SubsigCT a) -> Signal (SubsigCT b) -> Signal (SubsigCT c)Source

applyF2 works just like applyF1 but operates on two incoming signals.

applyG1 :: Num b => (a -> (Rational -> b) -> a) -> a -> Signal (SubsigCT b) -> aSource

applyG1 is used to apply a next-state function. A very interesting question is, what should be an argument to the next-state function: the incoming function, defining the value of the input signal? or the incoming function and the incoming interval? or the value of the incoming signal at a particular point, e.g. at the left most point of the interval? To give the next-state function the interval itself as argument, would mean that the process becomes time variant process, i.e. its behaviour is dependent on the absolute time values. This is not a good thing to have! Another possibility may be to give a sub-signal that is relative to the current evaluation, i.e. the left most point is always 0. Would that make sense?

cutEq :: (Num a, Num b) => Signal (SubsigCT a) -> Signal (SubsigCT b) -> (Signal (SubsigCT a), Signal (SubsigCT b))Source

cutEq partitions the two signals such that the partitioning are identical in both result signals, but only up to the duration of the shorter of the two signals:

# Sampling, printing and plotting

Several functions are available to display a signal in textual or graphics form. All displaying of signals is based on sampling and evaluation the signal at regular sampling points.

The function `sample`

evaluates the signal and returns a list of
(time,value) pairs, which can be displayed as text or used in any other way.

`showParts`

does not evaluate the signal; it only shows how it is
partitioned. Hence, it returns a sequence of intervals.

`plot`

, `plotCT`

and `plotCT'`

can plot a signal or a list of signals
in a graph. They use `gnuplot`

for doing the actual work.
They are in the IO monad because they write to the file system.

`plot`

is defined in terms of `plotCT`

but it uses the default sampling
period `timeStep`

and it can plot only one signal in a plot.

`plotCT`

can plot a list of signals in the same plot.
`plotCT`

is defined in terms of `plotCT'`

but uses
default label names for the plot.

`vcdGen`

writes the values of signals in Value Change Dump (VCD) format to
a file. There are public domain wave viewers which understand this format
and can display the signals.

`plot`

plots one signal in a graph with the default sampling period
of 1/200 of the duration of the signal.

:: Num a | |

=> Rational | The sampling period |

-> [Signal (SubsigCT a)] | The list of signals to be ploted in the same graph |

-> IO String | A messeage reporting what has been done. |

`plotCT`

plots a list of signals in the same graph. The sampling period
has to be given as argument. In the graph default label names are used
to identify the signals.

:: Num a | |

=> Rational | Sampling period |

-> [(Signal (SubsigCT a), String)] | A list of (signal,label) pairs. The signals are plotted and denoted by the corresponding labels in the plot. |

-> IO String | A simple message to report completion |

`plotCT'`

is the work horse for plotting and the functions `plot`

and
`plotCT`

use it with specialising arguments.

`plotCT'`

plots all the signals in the list in one graph. If a label is
given for a signal, this label appears in the graph. If the label string is
"", a default label like "sig-1" is used.

In addition to displaying the graph on the screen, the following files are created in directory ./fig:

- ct-moc-graph.eps
- an eps file of the complete graph
- ct-moc-graph.pdf
- A pdf file of the complete graph
- ct-moc-graph-latex.eps
- included by ct-moc-graph-latex.tex
- ct-moc-graph-latex.tex
- This is the tex file that should be included by your latex document. It in turn includes the file ct-moc-graph-latex.eps. These two files have to be used together; the .eps file contains only the graphics, while the .tex file contains the labels and text.

:: Num a | |

=> Signal (SubsigCT a) | The partitioned signal |

-> [(Double, Double)] | The sequence of intervals |

`showParts`

allows to see how a signal is partitioned into sub-signals.
It returns the sequence of intervals.

:: Num a | |

=> Rational | Sampling period; defines for what time stamps the values are written. |

-> [(Signal (SubsigCT a), String)] | A list of (signal,label) pairs. The signal values written and denoted by the corresponding labels. |

-> IO String | A simple message to report completion |

vcdGen dumps the values of a list of signal in VCD (Value Change Dump) format (IEEE Std 1364-2001), which is part of the Verilog standard (http://en.wikipedia.org/wiki/Value_change_dump). There are public domain tools to view VCD files. For instance, GTKWave (http://home.nc.rr.com/gtkwave/) is a popular viewer available for Windows and Linux.

The values are written to the file .*fig*ct-moc.vcd. If the file exists, it
is overwritten. If the directory does not exist, it is created.