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.

classDiagram Serializable <|-- BitErrorEvaluator Serializable <|-- BlockErrorEvaluator EvaluationTemplate <|-- FrameErrorEvaluation CommunicationEvaluator <|-- BitErrorEvaluator ArtifactTemplate <|-- BlockErrorArtifact Serializable <|-- FrameErrorEvaluator ArtifactTemplate <|-- ThroughputArtifact ArtifactTemplate <|-- FrameErrorArtifact ArtifactTemplate <|-- BitErrorArtifact CommunicationEvaluator <|-- BlockErrorEvaluator FrameErrorEvaluator <|-- ThroughputEvaluator Evaluator <|-- CommunicationEvaluator CommunicationEvaluator <|-- FrameErrorEvaluator EvaluationTemplate <|-- ThroughputEvaluation EvaluationTemplate <|-- BlockErrorEvaluation EvaluationTemplate <|-- BitErrorEvaluation Serializable <|-- ThroughputEvaluator

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)

Bases: Evaluator, ABC

Base class for evaluating communication processes between two modems.

Parameters
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 (List[GridDimension]) – The Simulation grid.

  • artifacts (np.ndarray) – Numpy object array whose dimensions represent grid dimensions.

Return type

EvaluationResult

Returns

The evaluation result.

class BitErrorArtifact(artifact)

Bases: ArtifactTemplate[float]

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

Parameters

artifact (AT) – Artifact value.

to_scalar()

Scalar representation of this artifact’s content.

Used to evaluate premature stopping criteria for the underlying evaluation.

Returns

Scalar floating-point representation. None if a conversion to scalar is impossible.

Return type

Optional[float]

class BitErrorEvaluation(evaluation)

Bases: EvaluationTemplate[ndarray]

Bit error evaluation of a single communication process between modems.

plot(axes=None)
Return type

List[Figure]

artifact()

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type

BitErrorArtifact

evaluation: ET
class BitErrorEvaluator(transmitting_modem, receiving_modem)

Bases: CommunicationEvaluator, Serializable

Evaluate bit errors between two modems exchanging information.

Parameters
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[float]

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

Parameters

artifact (AT) – Artifact value.

to_scalar()

Scalar representation of this artifact’s content.

Used to evaluate premature stopping criteria for the underlying evaluation.

Returns

Scalar floating-point representation. None if a conversion to scalar is impossible.

Return type

Optional[float]

class BlockErrorEvaluation(evaluation)

Bases: EvaluationTemplate[ndarray]

Block error evaluation of a single communication process between modems.

plot()
Return type

List[Figure]

artifact()

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type

BitErrorArtifact

evaluation: ET
class BlockErrorEvaluator(transmitting_modem, receiving_modem)

Bases: CommunicationEvaluator, Serializable

Evaluate block errors between two modems exchanging information.

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

to_scalar()

Scalar representation of this artifact’s content.

Used to evaluate premature stopping criteria for the underlying evaluation.

Returns

Scalar floating-point representation. None if a conversion to scalar is impossible.

Return type

Optional[float]

class FrameErrorEvaluation(evaluation)

Bases: EvaluationTemplate[ndarray]

Frame error evaluation of a single communication process between modems.

plot()
Return type

List[Figure]

artifact()

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type

FrameErrorArtifact

evaluation: ET
class FrameErrorEvaluator(transmitting_modem, receiving_modem)

Bases: CommunicationEvaluator, Serializable

Evaluate frame errors between two modems exchanging information.

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

to_scalar()

Scalar representation of this artifact’s content.

Used to evaluate premature stopping criteria for the underlying evaluation.

Returns

Scalar floating-point representation. None if a conversion to scalar is impossible.

Return type

Optional[float]

class ThroughputEvaluation(bits_per_frame, frame_duration, frame_errors)

Bases: EvaluationTemplate[ndarray]

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

artifact()

Generate an artifact from this evaluation.

Returns: The evaluation artifact.

Return type

ThroughputArtifact

class ThroughputEvaluator(transmitting_modem, receiving_modem)

Bases: FrameErrorEvaluator, Serializable

Evaluate data throughput between two modems exchanging information.

Parameters
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