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.

PropertyDescription
Description'Error Rate Test Console'. Read-only.
SystemUnderTestNameSystem 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.

IterationModeSpecify 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 ith sweep value set consists of the ith 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.

Note that for the following sweep parameter settings:

  • Parameter1 = [a1 a2]

  • Parameter2 = [b1 b2]

  • Parameter3 = [c1]

In Indexed Mode, the test console performs simulations for the following sweep parameter sets:
(a1, b1, c1)
(a2, b2, c1)

In Combinatorial Mode, the test console performs simulations for the following sweep parameter sets:
(a1, b1, c1)
(a1, b2, c1)
(a2, b1, c1)
(a2, b2, c1)
SystemResetModeSpecify 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.

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

  • Setting this property to Number of errors and transmissions stops the simulation for a sweep parameter point when meeting the following condition.

    • The simulation stops when the number of transmissions and the number errors have at least reached the values in MinNumTransmissions and MinNumErrors.

Set TransmissionCountTestPoint to the name of the registered test point that contains the transmission count you are comparing to the MaxNumTransmissions property.

To control the simulation length, 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.

MaxNumTransmissionsSpecify 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.
MinNumErrorsSpecify 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.
TransmissionCountTestPointSpecify 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, Number of errors or transmissions, or Number of errors and transmissions. In this scenario, if you register a test point, and TransmissionCountTestPoint equals Not set, the value of this property automatically updates to that of the registered test point name. Call the info method to see the valid test point names.
ErrorCountTestPointSpecify 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, Number of errors or transmissions, or Number of errors and transmissions. In this scenario, if you register a test point, and ErrorCountTestPoint equals Not set, the value of this property automatically updates to that of the registered test point name. 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 parpool 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 set 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. It can be a row vector of numeric values, or a cell array of char values. Display the valid ranges using the getTestParameterValidRanges method.

setTestParameterSweepValues(h,name1,sweep1,name2,sweep2...) simultaneously specifies sweep values for multiple registered test parameters.

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)

This example generates a figure similar to the following:

Was this topic helpful?