commtest.ErrorRate - Create error rate test console

Syntax

h = commtest.ErrorRate h = commtest.ErrorRate(sys) h = commtest.ErrorRate(sys,'PropertyName',PropertyValue,...) h = commtest.ErrorRate('PropertyName',PropertyValue,...)

Description

h = commtest.ErrorRate returns an error rate test console, h. The error rate test console runs simulations of a system under test to obtain error rates.

h = commtest.ErrorRate(sys) returns an error rate test console, error rate test console, h, with each specified property set to the h, with an attached system under test, SYS.

h = commtest.ErrorRate(sys,'PropertyName',PropertyValue,...) returns an error rate test console, h, with an attached system under test, sys. Each specified property, 'PropertyName', is set to the specified value, PropertyValue.

h = commtest.ErrorRate('PropertyName',PropertyValue,...) returns an error rate test console, h, with each specified property 'PropertyName', set to the specified value, PropertyValue.

Properties

The error rate test console object has the properties in the following table. Setting any property resets the object. A property that is irrelevant is one that you can set, but its value does not affect measurements. Similarly, you cannot display irrelevant properties using the disp method. You can write to all properties, except for the ones explicitly noted otherwise.

Property	Description
Description	'Error Rate Test Console'. Read-only.
SystemUnderTestName	System under test name. Read-only.
FrameLength	Specify the length of the transmission frame at each iteration. This property becomes relevant only when the system under test registers a valid test input. If the system under test registers a `NumTransmissions` test input and calls its `getInput` method, the error rate test console returns the value stored in `FrameLength`. Using an internal data source, the system under test uses this value to generate a transmission frame of the specified length. If the system under test registers a `DiscreteRandomSource` test input and calls its `getInput` method, the test console generates and returns a frame of symbols. The length of the frame of symbols matches the `FrameLength` property. This property defaults to 500.
IterationMode	Specify how the object determines simulation points. If set to `Combinatorial`, the object performs simulations for all possible combinations of registered test parameter sweep values. If set to `Indexed`, the object performs simulations for all indexed sweep value sets. The i^th sweep value set consists of the i^th element of every sweep value vector for each registered test parameter. All sweep value vectors must have equal length, except for values that are unit length.
SystemResetMode	Specify the stage of a simulation run at which the system resets. Setting to `Reset at new simulation point` resets the system under test at the beginning of a new simulation point. Setting to `Reset at every iteration` resets the system under test at every iteration.
SimulationLimitOption	Specify how to stop the simulation for each sweep parameter point. If set to `Number of transmissions` the simulation for a sweep parameter point stops when the number of transmissions equals the value for `MaxNumTransmissions`. Set `TransmissionCountTestPoint` to the name of the registered test point containing the transmission count you are comparing to `MaxNumTransmissions`. If set to `Number of errors` the simulation for a sweep parameter point stops when the number of errors equals the value for `MinNumErrors`. Set the `ErrorCountTestPoint` to the name of the registered test point containing the error count you are comparing to the `MinNumErrors`. Setting to `Number of errors or transmissions` stops the simulation for a sweep parameter point when meeting one of two conditions. The simulation stops when the number of transmissions equals the value for `MaxNumTransmissions`. The simulation stops when obtaining the number of errors matching `NumErrors`. Set `TransmissionCountTestPoint` to the name of the registered test point that contains the transmission count you are comparing to the `MaxNumTransmissions` property. Set `ErrorCountTestPoint` to the name of the registered test point containing the error count you are comparing to `MinNumErrors`. Call the `info` method of the error rate test console to see the valid registered test point names.
MaxNumTransmissions	Specify the maximum number of transmissions the object counts before stopping the simulation for a sweep parameter point. This property becomes relevant only when `SimulationLimitOption` is `Number of transmissions` or `Number of errors or transmissions`. When setting `SimulationLimitOption` to `Number of transmissions` the simulation for each sweep parameter point stops when reaching the number of transmissions `MaxNumTransmissions` specifies. Setting `SimulationLimitOption` to `Number of errors or transmissions` stops the simulation for each sweep parameter point for one of two conditions. The simulation stops when completing the number of transmissions `MaxNumTransmissions` specifies. The simulation stops when obtaining the number of errors `MinNumErrors` specifies. The `TransmissionCountTestPoint` property supplies the name of a registered test point containing the count transmission type. Calling the `info` method of the error rate test console displays the valid registered test points. If this property contains registered test points, the test console runs iterations equal to the value for `MaxNumTransmissions` for each sweep parameter point. If this property has no registered test parameters, the test console runs the number of iterations equal to the value for `MaxNumTransmissions` and stops. The value defaults to 1000.
MinNumErrors	Specify the minimum number of errors the object counts before stopping the simulation for a sweep parameter point. This property becomes relevant only when setting the `SimulationLimitOption` to `Number of errors` or `Number of errors or transmissions`. When setting `SimulationLimitOption` to `Number of errors` the simulation for each parameter point stops when reaching the number of errors you specify for the `MinNumErrors` property. When setting the `SimulationLimitOption` property to `Number of errors or transmissions` the simulation for each sweep parameter point stops for one of two conditions. The simulation stops when reaching the number of errors you specify for the `MaxNumTransmissions` property. The simulation stops when reaching the number of errors you specify for the `MinNumErrors` property. Specify the type of errors the error count uses by setting the `ErrorCountTestPoint` property to the name of a registered test point containing the count. Call the `info` method of the error rate test console to see the valid registered test point names. This value defaults to 100.
TransmissionCountTestPoint	Specify and register a test point containing the transmission count that controls the test console simulation stop mechanism. This property becomes relevant only when setting `SimulationLimitOption` to `Number of transmissions` or `Number of errors or transmissions`. Call the `info` method to see the valid test point names.
ErrorCountTestPoint	Specify and register the name of a test point containing the error count that controls the simulation stop mechanism. This property is only relevant when setting the `SimulationLimitOption` property to `Number of errors` or `Number of errors or transmissions`. Call the `info` method to see the valid test point names.

Methods

The error rate test console object has the following methods:

run

Runs a simulation.

Runs the number of error rate simulations you specify for a system under test with a specified set of parameter values. If a Parallel Computing Toolbox™ license is available and a matlabpool is open, then the object distributes the iterations among the number of workers available.

getResults

Returns the simulation results.

r = getResults(h) returns the simulation results, r, for the test console, h. r is an object of the type you specify using testconsole.Results. It contains the simulation data for all the registered test points and methods to parse the data and plot it.

info

Returns a report of the current test console settings.

info(h) displays the current test console settings, such as registered test parameters and registered test points.

reset

Resets the error rate test console.

reset(h) resets test parameters and test probes and then clears all simulation results of test console, h.

attachSystem

Attaches a system to test console.

attachSystem(ho,sys) attaches a valid user-defined system, sys, to the test console, h.

detachSystem

Detaches the system from the test console.

detachSystem(h) detaches a system from the test console, h. This method also clears the registered test inputs, test parameters, test probes, and test points.

setTestParameterSweepValues

Sets test parameter sweep values.

setTestParameterSweepValues(h,name,sweep) specifies a vector of sweep values, 'sweep', for the registered test parameter, name, in the test console, h. You only specify sweep values for registered test parameters. sweep must have values within the specified range of the test parameter. Display the valid ranges using the getTestParameterValidRanges method.

getTestParameterSweepValues

Returns test parameter sweep values.

getTestParameterSweepValues(h,name) gets the sweep values currently specified for the registered test parameter, name, in the test console, h.

getTestParameterValidRanges

Returns the test parameter valid ranges.

getTestParameterValidRanges(h,name) gets the valid ranges for a registered test parameter, name, in the test console, h.

registerTestPoint

Registers a test point.

registerTestPoint(h, name, actprobe,expprobe) registers a new test point object, name, to the error rate test console, h. The test point must contain a pair of registered test probes, actprobe, and expprobe. actprobe contains actual data, and expprobe contains expected data. The object compares the data from these probes and obtains error rate values. The error rate calculation uses a default error rate calculator function that simply performs one-to-one comparisons of the data vectors available in the probes.

registerTestPoint(h, name, actprobe,expprobe, handle) adds the handle, handle, to a user-defined error calculation function that compares the data in the probes and then obtains error rate results.

The user-defined error calculation function must comply with the following syntax: [ecnt tcnt] = functionName(act, exp, udata) where

ecnt output corresponds to the error count
tcnt output is the number of transmissions used to obtain the error count
act and exp correspond to actual and expected data

The error rate test console sets the inputs to the data available in the pair of test point probes, actprobe, and expprobe.

udata is a data input that the system under test passes to the test console at run time, using the setUserData method. udata contains the data necessary to compute errors, such as delays and data buffers.

The error rate test console passes the data that the system under test logs to the error calculation functions for all the registered test points. Calling the info method returns the names of the registered test points and the error rate calculator functions associated with them. It also returns the names of the registered test probes.

unregisterTestPoint

Unregister a test point.

unregisterTestPoint(h,name) removes the test point, name, from the test console, h.

Examples

% Obtain bit error rate and  symbol error rate of an M-PSK system
% for different modulation orders and EbNo values. 
  
% Instantiate an ErrorRate test console. The default error rate
% test console has an M-PSK system attached. 
       h = commtest.ErrorRate; 
  
% Set sweep values for simulation test parameters
setTestParameterSweepValues(h,'M',2.^[1 2 3 4])
setTestParameterSweepValues(h,'EbNo',(-5:5))
    
% Register test points 
registerTestPoint(h,'SymbolErrorRate','TxInputSymbols',...,
'RxOutputSymbols')
registerTestPoint(h,'BitErrorRate','TxInputBits','RxOutputBits')
       
% Set simulation stop criteria.
h.TransmissionCountTestPoint = 'SymbolErrorRate';
 
% Get information about the simulation settings
info(h)
 
% Run the MPSK simulations 
run(h)
  
% Get the results
R = getResults(h);
       
% Plot EbNo versus bit error rate for different values of modulation
% order M
R.TestParameter2 = 'M';
plot(R)