Communication Evaluators#

This module introduces several evaluators for performance indicators in communication scenarios. Refer to the PyMonte documentation for a detailed introduction to the concept of Evaluators.

The implemented CommunicationEvaluators all inherit from the identically named common base which gets initialized by selecting the two Modem instances whose communication should be evaluated. The currently considered performance indicators are

Evaluator	Artifact	Performance Indicator
`BitErrorEvaluator`	`BitErrorArtifact`	Errors comparing two bit streams
`BlockErrorEvaluator`	`BlockErrorArtifact`	Errors comparing two bit streams divided into blocks
`FrameErrorEvaluator`	`FrameErrorArtifact`	Errors comparing two bit streams divided into frames
`ThroughputEvaluator`	`ThroughputArtifact`	Rate of correct frames multiplied by the frame bit rate

Configuring CommunicationEvaluators to evaluate the communication process between two Modem instances is rather straightforward:

# Create two separate modem instances
modem_alpha = Modem()
modem_beta = Modem()

# Create a bit error evaluation as a communication evaluation example
communication_evaluator = BitErrorEvaluator(modem_alpha, modem_beta)

# Extract evaluation artifact
communication_artifact = communication_evaluator.evaluate()

# Visualize artifact
communication_artifact.plot()

class CommunicationEvaluator(transmitting_modem, receiving_modem, plot_surface=True)#

Bases: Evaluator, ABC

Base class for evaluating communication processes between two modems.

Parameters:

transmitting_modem (TransmittingModem) – Modem transmitting information.
receiving_modem (ReceivingModem) – Modem receiving information.
plot_surface (bool, optional) – Plot the surface of the evaluation result in two-dimensional grids. Defaults to True.

property transmitting_modem: TransmittingModem#

Modem transmitting information.

Returns:: Handle to the transmitting modem.
Return type:: Modem

property receiving_modem: ReceivingModem#

Modem receiving information.

Returns:: Handle to the receiving modem.
Return type:: Modem

generate_result(grid, artifacts)#

Generates an evaluation result from the artifacts collected over the whole simulation grid.

Parameters:

grid (Sequence[GridDimension]) – The Simulation grid.
artifacts (np.ndarray) – Numpy object array whose dimensions represent grid dimensions.

Return type:

ScalarEvaluationResult

Returns:

The evaluation result.

class BitErrorArtifact(artifact)#

Bases: ArtifactTemplate[float64]

Artifact of a bit error evaluation between two modems exchanging information.

Parameters:: artifact (AT) – Artifact value.

class BitErrorEvaluation(evaluation)#

Bases: EvaluationTemplate[ndarray]

Bit error evaluation of a single communication process between modems.

property title: str#

Title of the visualizable.

Returns: Title string.

artifact()#

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type:: BitErrorArtifact

class BitErrorEvaluator(transmitting_modem, receiving_modem, plot_surface=True)#

Bases: CommunicationEvaluator, Serializable

Evaluate bit errors between two modems exchanging information.

Parameters:

transmitting_modem (TransmittingModem) – Modem transmitting information.
receiving_modem (ReceivingModem) – Modem receiving information.
plot_surface (bool, optional) – Plot the surface of the evaluation result in two-dimensional grids. Defaults to True.

yaml_tag: Optional[str] = 'BitErrorEvaluator'#: YAML serialization tag

evaluate()#

Evaluate the state of an investigated object.

Implements the process of extracting an arbitrary performance indicator, represented by the returned Artifact \(X_m\). :returns: Artifact \(X_m\) resulting from the evaluation. :rtype: Artifact

property abbreviation: str#

Short string representation of this evaluator.

Used as a label for console output and plot axes annotations.

Returns:: String representation
Return type:: str

property title: str#

Long string representation of this evaluator.

Used as plot title.

Returns:: String representation
Return type:: str

class BlockErrorArtifact(artifact)#

Bases: ArtifactTemplate[float64]

Artifact of a block error evaluation between two modems exchanging information.

Parameters:: artifact (AT) – Artifact value.

class BlockErrorEvaluation(evaluation)#

Bases: EvaluationTemplate[ndarray]

Block error evaluation of a single communication process between modems.

property title: str#

Title of the visualizable.

Returns: Title string.

artifact()#

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type:: BitErrorArtifact

class BlockErrorEvaluator(transmitting_modem, receiving_modem, plot_surface=True)#

Bases: CommunicationEvaluator, Serializable

Evaluate block errors between two modems exchanging information.

Parameters:

transmitting_modem (TransmittingModem) – Modem transmitting information.
receiving_modem (ReceivingModem) – Modem receiving information.
plot_surface (bool, optional) – Plot the surface of the evaluation result in two-dimensional grids. Defaults to True.

yaml_tag: Optional[str] = 'BlockErrorEvaluator'#: YAML serialization tag

evaluate()#

Evaluate the state of an investigated object.

Implements the process of extracting an arbitrary performance indicator, represented by the returned Artifact \(X_m\). :returns: Artifact \(X_m\) resulting from the evaluation. :rtype: Artifact

property title: str#

Long string representation of this evaluator.

Used as plot title.

Returns:: String representation
Return type:: str

property abbreviation: str#

Short string representation of this evaluator.

Used as a label for console output and plot axes annotations.

Returns:: String representation
Return type:: str

class FrameErrorArtifact(artifact)#

Bases: ArtifactTemplate[float]

Artifact of a frame error evaluation between two modems exchanging information.

Parameters:: artifact (AT) – Artifact value.

class FrameErrorEvaluation(evaluation)#

Bases: EvaluationTemplate[ndarray]

Frame error evaluation of a single communication process between modems.

property title: str#

Title of the visualizable.

Returns: Title string.

artifact()#

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type:: FrameErrorArtifact

class FrameErrorEvaluator(transmitting_modem, receiving_modem, plot_surface=True)#

Bases: CommunicationEvaluator, Serializable

Evaluate frame errors between two modems exchanging information.

Parameters:

transmitting_modem (TransmittingModem) – Modem transmitting information.
receiving_modem (ReceivingModem) – Modem receiving information.
plot_surface (bool, optional) – Plot the surface of the evaluation result in two-dimensional grids. Defaults to True.

yaml_tag: Optional[str] = 'FrameErrorEvaluator'#: YAML serialization tag

evaluate()#

Evaluate the state of an investigated object.

Implements the process of extracting an arbitrary performance indicator, represented by the returned Artifact \(X_m\). :returns: Artifact \(X_m\) resulting from the evaluation. :rtype: Artifact

property title: str#

Long string representation of this evaluator.

Used as plot title.

Returns:: String representation
Return type:: str

property abbreviation: str#

Short string representation of this evaluator.

Used as a label for console output and plot axes annotations.

Returns:: String representation
Return type:: str

class ThroughputArtifact(artifact)#

Bases: ArtifactTemplate[float]

Artifact of a throughput evaluation between two modems exchanging information.

Parameters:: artifact (AT) – Artifact value.

class ThroughputEvaluation(bits_per_frame, frame_duration, frame_errors)#

Bases: EvaluationTemplate[float]

Throughput evaluation between two modems exchanging information.

Parameters:

bits_per_frame (int) – Number of bits per communication frame
frame_duration (float) – Duration of a single communication frame in seconds
frame_errors (np.ndarray) – Frame error indicators

property title: str#

Title of the visualizable.

Returns: Title string.

artifact()#

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type:: ThroughputArtifact

class ThroughputEvaluator(transmitting_modem, receiving_modem, plot_surface=True)#

Bases: CommunicationEvaluator, Serializable

Evaluate data throughput between two modems exchanging information.

Parameters:

transmitting_modem (TransmittingModem) – Modem transmitting information.
receiving_modem (ReceivingModem) – Modem receiving information.
plot_surface (bool, optional) – Plot the surface of the evaluation result in two-dimensional grids. Defaults to True.

yaml_tag: Optional[str] = 'ThroughputEvaluator'#: YAML serialization tag

evaluate()#

Evaluate the state of an investigated object.

Implements the process of extracting an arbitrary performance indicator, represented by the returned Artifact \(X_m\). :returns: Artifact \(X_m\) resulting from the evaluation. :rtype: Artifact

property title: str#

Long string representation of this evaluator.

Used as plot title.

Returns:: String representation
Return type:: str

property abbreviation: str#

Short string representation of this evaluator.

Used as a label for console output and plot axes annotations.

Returns:: String representation
Return type:: str