Overview

Robochameleon is a coding framework and component library for simulation and experimental analysis of optical communication systems. This is a quick start guide to using the framework; descriptions of components can be found in the corresponding class definitions.

We use classes to ensure standardization for both signal representation and functions. This guide has a brief introduction to classes, but if you are familiar with object oriented programming, you should skip it.

Setting up

The Robochameleon project is stored in multiple folders, which all must be in Matlab's search path for the code to run. The script robochameleon.m will automatically add these to the path.

There are also some toolbox dependencies, as well as some function calls to relatively new features in Matlab. When possible, we have added alternatives in the compatibility folder. The initialization script does some automatic detection of what features the user has, but is not perfect, and in some cases it might be necessary to add these folders manually. In particular, [module] uses the bioinformatics toolbox, so the folder \compatibility\bioinfolite should be in the path if the user does not have a license.

Classes

Classes ensure standardization for a large function library. They facilitate block data processing and internal state saving. For a complete introduction to classes using Matlab, there are some useful tutorials on Matlab Central.

Here is a very simple (and totally useless) example of a class that adds two numbers together:

classdef Adder

    properties
        a;
        b;
        sum;
     end
     
    methods
    
        function obj = Adder(param)
            obj.a = param.a;
            obj.b = param.b;            
        end
       
        function obj = plus(obj)
             obj.sum = obj.a+obj.b;
        end
    end
end

A class basically consists of two things:

1. Properties. These are analogous to parameters passed to a function.
2. Methods. These are analogous to functions.

All classes must have a method (called the constructor) that creates an object of that class. In the above example, that was:

        function obj = Adder(param)
            obj.a = param.a;
            obj.b = param.b;            
        end

In the above example, there is an additional method called plus that contains the main function. To use this class, one would first make an adder using the constructor:

>>test = Adder(struct('a', 1, 'b', 3));
>>disp(test)
  Properties:
    a: 1
    b: 3
    sum: []
  Methods

Note the addition has not been performed yet. Then to perform the pre-defined operation:

>> test.plus
ans = 
  Adder
  Properties:
    a: 1
    b: 3
    sum: 4
  Methods

Note all other operations are prohibited:

>> test.minus
No appropriate method, property, or field minus for class adder

Robochameleon classes

In Robochameleon, there are four basic classes:

1. pwr for representing signal power
2. signal_interface for representing a waveform
3. unit for representing an element in a communication system
4. module a collection of units, including connections between them

The full documentation set has reference pages for each class with documentation of all properties and methods. Below, we have a more general introduction to the most important properties and methods, as well as descriptions of how these are meant to interact.

Signal representation

Signals are described using two classes, pwr and signal_interface. Each signal_interface object has a property (signal_interface.PCol) that is an array of pwr objects. An array is used so that one pwr object describes the power contained in each each component (polarization) of the waveform.

Power representation (pwr)

Typically signal power is represented as an object of type pwr. The two main properties are

1. the signal-to-noise ratio, and
2. the signal power.

Note that the SNR is not always well-defined (e.g. this value doesn't mean much after propagation through a nonlinear channel). The primary purpose of tracking SNR is to help understand what limits performance of a simulated system, but sometimes some discretion in interpreting this value is required.

The signal power and noise powers are defined as the total powers in the bandwidth of the signal waveform (i.e. the sampling rate Fs). Thus if a large oversampling ratio (e.g. 16 samples per symbol) is used, then the SNR of the signal will be much worse than the SNR of an equivalent signal in a real system.

There are a number of useful methods in the pwr class, including addition, scalar multiplication, and several display and unit conversion functions. These are documented in the class itself. For an example of how to use pwr objects, consult run_Testpwr.m in \Setups\Demo.

Other signal properties (signal_interface)

All signals must be represented as objects of type signal_interface. They have the following user-specified properties:

1. E, the waveform (in arbitrary units)
2. Fs, the sampling rate (Hz)
3. Fc, the carrier frequency (Hz)
4. Rs, the symbol rate (Hz)
5. PCol, the signal power (array of pwr objects)

These quantites are also not always well-defined (e.g. the output of a laser has no symbol rate), but are nonetheless required. Not-a-number (nan) should be used in this case. signal_interface objects also have some derived properties:

1. N number of signal elements (polarizations)
2. Nss number of samples per symbol
3. ...

which can be read and used but not modified.

Here is a very simple example of how to construct a signal interface object and what the display function looks like:

>> sig_param =struct('Rs',10e9,'Fs',40e9,'Fc',const.c/1550e-9,'PCol',[pwr(inf, 27), pwr(inf, 27)]);
>> sig_mat = randn(100,2); % 2-component random signal
>> sig_obj = signal_interface(sig_mat,sig_param)
Real signal
	Length: 100 Sa
	Number of components: 2
	Symbol rate: 10.0 GBd (100.0 ps)
	Sampling rate: 40.00 GHz (25.00 ps)
	Oversampling ratio: 4.00 Sa/symbol
	Carrier frequency: 193.414 THz (1.55000 um)
	Total power: 30.03 dBm (1006.49 mW)
	SNR: Inf dB (Inf)
	Signal power: 30.03 dBm (1006.49 mW)
	Noise power: -Inf dBm (0.00 mW)
>>

There are a number of useful methods in signal_interface that are documented there. Most notably, there are methods to apply functions to signals and add signals to each other such that power and SNR are tracked automatically.

Relationship between power and waveform

Note that the waveform amplitude (signal_interface.PCol) is specified separately from the waveform shape (signal_interface.E). This can lead to un-intended results when the two are in conflict. It is important to always use the appropriate get and set-like (signal_interface.fun1, signal_interface.plus, signal_interface.mtimes) methods when manipulating waveforms.

For an extended example, see run_TestSignalInterface.m and run_TestSignalInterfaceAdvanced.m in \setups\_Demo

Block-based program structure (unit & module)

Every function that can be applied to a signal_interface object is encapsulated in a unit. Multiple units can be collected into a super-unit, which is called a module.

Units

Everything that operates on a signal_interface object should be defined as a class that inherits certain properties from [unit]. For example:

classdef MyClass_v1 < unit
  ...
end

classdef MyModule_v1 < module
    
    properties
        nInputs = 2;
        nOutputs = 4;
    end
    
    methods
        function obj = MyModule_v1(param)
            % Units
            a = A(param.paramA);
            b = B(param.paramB);
            c = C(param.paramC);
            d = D(param.paramD);
            
            % Connections
            obj.connectInputs({a b},[1 1])
            a.connectOutputs(c,1);
            b.connectOutputs(c,2);
            c.connectOutputs({d obj.outputBuffer obj.outputBuffer},[1 3 4])
            d.connectOutputs({obj.outputBuffer obj.outputBuffer},[1 2]);
            
            obj.exportModule();
        end
    end
    
end