Merge branch '168-noise-power-property' into 'master'

Object-Oriented Noise Configuration Closes #168 See merge request barkhauseninstitut/wicon/hermespy!178
Barkhausen-Institut · Apr 5, 2024 · 1160788 · 1160788
2 parents 027953c + 0624e98
commit 1160788
Show file tree

Hide file tree

Showing 110 changed files with 1,413 additions and 773 deletions.
diff --git a/_examples/library/getting_started_simulation.py b/_examples/library/getting_started_simulation.py
@@ -2,7 +2,7 @@
 
 from hermespy.core import dB
 from hermespy.channel import MultipathFading5GTDL
-from hermespy.simulation import Simulation
+from hermespy.simulation import Simulation, SNR
 from hermespy.modem import BitErrorEvaluator, SimplexLink, RootRaisedCosineWaveform, SingleCarrierLeastSquaresChannelEstimation, SingleCarrierZeroForcingChannelEqualization
 
 # Create a new simulation
@@ -12,6 +12,10 @@
 tx_device = simulation.new_device()
 rx_device = simulation.new_device()
 
+# Specify the hardware noise model
+tx_device.noise_level = SNR(dB(20), tx_device)
+rx_device.noise_level = SNR(dB(20), tx_device)
+
 # Specifiy the channel instance linking the two devices
 simulation.set_channel(tx_device, rx_device, MultipathFading5GTDL())
 
@@ -43,7 +47,7 @@
 ber.evaluate().visualize()
 
 # Iterate over the receiving device's SNR and estimate the respective bit error rates
-simulation.new_dimension('snr', dB(20, 16, 12, 8, 4, 0), rx_device)
+simulation.new_dimension('noise_level', dB(20, 16, 12, 8, 4, 0), rx_device)
 simulation.add_evaluator(ber)
 
 result = simulation.run()

diff --git a/_examples/library/getting_started_simulation_multidim.py b/_examples/library/getting_started_simulation_multidim.py
@@ -1,7 +1,7 @@
 import matplotlib.pyplot as plt
 
 from hermespy.core import dB
-from hermespy.simulation.simulation import Simulation
+from hermespy.simulation import Simulation, SNR
 from hermespy.modem import TransmittingModem, ReceivingModem, BitErrorEvaluator, ThroughputEvaluator, RootRaisedCosineWaveform
 from hermespy.fec import RepetitionEncoder
 
@@ -13,6 +13,11 @@
 base_station = simulation.scenario.new_device()
 terminal = simulation.scenario.new_device()
 
+
+# Specify the hardware noise model
+base_station.noise_level = SNR(dB(20), base_station)
+terminal.noise_level = SNR(dB(20), base_station)
+
 # Disable device self-interference by setting the gain
 # of the respective self-inteference channels to zero
 simulation.scenario.channel(base_station, base_station).gain = 0.
@@ -35,7 +40,7 @@
 simulation.add_evaluator(ThroughputEvaluator(transmitter, receiver, plot_surface=True))
 
 # Configure simulation sweep dimensions
-snr_dimension = simulation.new_dimension('snr', dB(12, 10, 8, 6, 5, 4, 3, 2, 1, 0))
+snr_dimension = simulation.new_dimension('noise_level', dB(12, 10, 8, 6, 5, 4, 3, 2, 1, 0), terminal)
 rep_dimension = simulation.new_dimension('repetitions', [1, 3, 5, 7, 9], transmitter.encoder_manager[0], receiver.encoder_manager[0])
 snr_dimension.title = 'SNR'
 rep_dimension.title = 'Code Repetitions'

diff --git a/_examples/matlab/getting_started_example2.m b/_examples/matlab/getting_started_example2.m
@@ -67,7 +67,7 @@
 channel_state = propagate{3};
 
 % define SNR
-snr = pyargs('snr',py.float(5));
+snr = pyargs('noise_level',py.float(5));
 rx_device.receive(rx_signal,snr);
 
 % function "receive()" returns a "tuple" type variable, where

diff --git a/_examples/paper/fec.py b/_examples/paper/fec.py
@@ -39,7 +39,7 @@
 tx_device.transmitters.add(tx_modem)
 rx_device.receivers.add(rx_modem)
 
-simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
 simulation.add_evaluator(BitErrorEvaluator(tx_modem, rx_modem))
 simulation.add_evaluator(BlockErrorEvaluator(tx_modem, rx_modem))
 simulation.add_evaluator(FrameErrorEvaluator(tx_modem, rx_modem))

diff --git a/_examples/paper/hardware_effects.py b/_examples/paper/hardware_effects.py
@@ -31,7 +31,7 @@
 modem.waveform.channel_estimation = SingleCarrierLeastSquaresChannelEstimation()
 modem.waveform.channel_equalization = SingleCarrierZeroForcingChannelEqualization()
 
-simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
 simulation.add_evaluator(BitErrorEvaluator(modem, modem))
 simulation.num_samples, simulation.min_num_samples = 100000, 100000
 simulation.plot_results = True

diff --git a/_examples/paper/interference_alamouti.py b/_examples/paper/interference_alamouti.py
@@ -76,7 +76,7 @@
 evaluator.tolerance = .0
 evaluator.confidence = 1
 simulation.add_evaluator(evaluator)
-simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
 simulation.num_samples, simulation.min_num_samples = 10000, 10000
 simulation.plot_results = True
 simulation.scenario.set_seed(42)

diff --git a/_examples/paper/interference_no.py b/_examples/paper/interference_no.py
@@ -64,7 +64,7 @@
 evaluator.tolerance = .0
 evaluator.confidence = 1
 simulation.add_evaluator(evaluator)
-simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
 simulation.num_samples, simulation.min_num_samples = 100000, 100000
 simulation.plot_results = True
 simulation.scenario.set_seed(42)

diff --git a/_examples/paper/interference_zf.py b/_examples/paper/interference_zf.py
@@ -74,7 +74,7 @@
 evaluator.tolerance = .0
 evaluator.confidence = 1
 simulation.add_evaluator(evaluator)
-simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
 simulation.num_samples, simulation.min_num_samples = 100000, 100000
 simulation.plot_results = True
 simulation.scenario.set_seed(42)

diff --git a/_examples/paper/radar_sensing.py b/_examples/paper/radar_sensing.py
@@ -32,7 +32,7 @@
 simulation.results_dir = simulation.default_results_dir()
 simulation.plot_results = True
 simulation.scenario.snr_type = SNRType.PN0
-simulation.new_dimension('snr', [db2lin(snr) for snr in [-20, -10, 0]])
+simulation.new_dimension('noise_level', [db2lin(snr) for snr in [-20, -10, 0]])
 
 # Consider a device without interference in between operators
 device_h1 = simulation.new_device(carrier_frequency=70e9)

diff --git a/_examples/paper/stopping.py b/_examples/paper/stopping.py
@@ -50,7 +50,7 @@
     evaluator.confidence = confidence
     evaluator.tolerance = tolerance
 
-    simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+    simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
     simulation.add_evaluator(evaluator)
     simulation.num_samples = 100000
     simulation.min_num_samples = 100

diff --git a/_examples/paper/theory.py b/_examples/paper/theory.py
@@ -48,7 +48,7 @@
     modem.waveform.modulation_order = modulation_order
     simulation.scenario.set_channel(device, device, channel)
 
-    simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+    simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
     simulation.add_evaluator(BitErrorEvaluator(modem, modem))
     simulation.num_samples, simulation.min_num_samples = 100000, 100000
     simulation.plot_results = True

diff --git a/_examples/paper/theory_awgn.py b/_examples/paper/theory_awgn.py
@@ -42,7 +42,7 @@
     modem.waveform.modulation_order = modulation_order
     simulation.scenario.set_channel(device, device, channel)
 
-    simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+    simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
     simulation.add_evaluator(BitErrorEvaluator(modem, modem))
     simulation.num_samples, simulation.min_num_samples = 100000, 100000
     simulation.plot_results = True

diff --git a/_examples/paper/theory_rayleigh.py b/_examples/paper/theory_rayleigh.py
@@ -57,7 +57,7 @@
     modem.waveform.modulation_order = modulation_order
     simulation.scenario.set_channel(device, device, channel)
 
-    simulation.new_dimension('snr', [db2lin(x) for x in np.arange(-10, 20, .5)])
+    simulation.new_dimension('noise_level', [db2lin(x) for x in np.arange(-10, 20, .5)])
     simulation.add_evaluator(BitErrorEvaluator(modem, modem))
     simulation.num_samples, simulation.min_num_samples = 100000, 100000
     simulation.plot_results = True

diff --git a/_examples/settings/chirp_fsk_lora.yml b/_examples/settings/chirp_fsk_lora.yml
@@ -101,11 +101,13 @@ Evaluators:
 # Simulation parameters
 num_samples: 1000                  # Number of samples per simulation grid section
 min_num_samples: 50                # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # Noise is defined as the ratio between bit energy and noise power
+  reference: *link                 # The SNR is calculated with respect to the link waveform
+
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
-  snr: [10, 9, ..., -2] dB
+  noise_level: [10, 9, ..., -2] dB
diff --git a/_examples/settings/chirp_qam.yml b/_examples/settings/chirp_qam.yml
@@ -82,14 +82,15 @@ Evaluators:
 # Simulation parameters
 num_samples: 10000                 # Maximum number of samples per simulation grid section
 min_num_samples: 1000              # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *waveform             # The SNR is calculated with respect to the processed waveform
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
   # Sweep over the global receiver signal-to-noise ratio
-  - property: 'snr'
+  - property: 'noise_level'
     points: [0, 1, ..., 20] dB
 
   # Sweep over the wavform's modulation order to check QPSK, 16-QAM and 64-QAM

diff --git a/_examples/settings/hardware_model.yml b/_examples/settings/hardware_model.yml
@@ -69,10 +69,11 @@ Evaluators:
 # Simulation parameters
 num_samples: 10000                 # Number of samples per simulation grid section
 min_num_samples: 50                # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *modem_alpha          # The SNR is calculated with respect to the referenced modem's waveform power
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
-  snr: [0, 4, ..., 20] dB
+  noise_level: [0, 4, ..., 20] dB
diff --git a/_examples/settings/interference_ofdm_single_carrier.yml b/_examples/settings/interference_ofdm_single_carrier.yml
@@ -145,7 +145,8 @@ Evaluators:
 # Simulation parameters
 num_samples: 10                    # Number of samples per simulation grid section
 min_num_samples: 5                 # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *modem_beta           # The SNR is calculated with respect to the referenced modem's waveform power
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 

diff --git a/_examples/settings/jcas.yml b/_examples/settings/jcas.yml
@@ -115,13 +115,14 @@ Evaluators:
 
 
 # Simulation parameters
-num_samples: 1000                  # Number of samples per simulation grid section
-min_num_samples: 10                # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
-plot_results: True                 # Visualize the evaluations after the simulation has finished
+num_samples: 1000                   # Number of samples per simulation grid section
+min_num_samples: 10                 # Minimum number of samples per simulation grid section before premature stopping
+noise_level: !<EBN0>                # SNR is defined as the ratio between bit energy and noise power
+  reference: *base_station_operator # The SNR is calculated with respect to the referenced oeprators's waveform power
+plot_results: True                  # Visualize the evaluations after the simulation has finished
 
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
-  snr: [10, 8, ..., -10] dB
+  noise_level: [10, 8, ..., -10] dB
diff --git a/_examples/settings/ofdm_5g.yml b/_examples/settings/ofdm_5g.yml
@@ -146,13 +146,14 @@ Evaluators:
 # Simulation parameters
 num_samples: 1000                  # Number of samples per simulation grid section
 min_num_samples: 100               # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *ofdm                 # The SNR is calculated with respect to the referenced waveform's power 
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 num_actors: 1                      # This simulation is quite memory demanding. It might be necessary to limit the number of actors.
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
   # Sweep over the global receiver signal-to-noise ratio
-  - property: 'snr'
+  - property: 'noise_level'
     points: [0, 1, ..., 20] dB
diff --git a/_examples/settings/ofdm_single_carrier.yml b/_examples/settings/ofdm_single_carrier.yml
@@ -47,7 +47,7 @@ Operators:
       - !<SingleCarrier>       # Spatial Multiplexing
 
     # Configuration of the waveform emitted by this transmitter
-    waveform: !<OFDM>
+    waveform: &ofdm !<OFDM>
 
       # Modulation settings
       modulation_order: 16                  # Modulation order, in other words 4 bit per data resource element
@@ -108,11 +108,12 @@ Evaluators:
 # Simulation parameters
 num_samples: 1000                  # Number of samples per simulation grid section
 min_num_samples: 100               # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *ofdm                 # The SNR is calculated with respect to the processed waveform
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
-  snr: [20, 10, 2, 0] dB
+  noise_level: [20, 10, 2, 0] dB
diff --git a/_examples/settings/operator_separation.yml b/_examples/settings/operator_separation.yml
@@ -94,11 +94,12 @@ Evaluators:
 # Simulation parameters
 num_samples: 1000                  # Number of samples per simulation grid section
 min_num_samples: 50                # Minimum number of samples per simulation grid section before premature stopping
-snr_type: EBN0                     # SNR is defined as the ratio between bit energy and noise power
+noise_level: !<EBN0>               # SNR is defined as the ratio between bit energy and noise power
+  reference: *device_alpha         # The SNR is calculated with respect to the device's output power
 plot_results: True                 # Visualize the evaluations after the simulation has finished
 
 
 # Scenario parameters over which the Monte-Carlo simulation sweeps
 Dimensions:
 
-  snr: [10, 9, ..., -2] dB
+  noise_level: [10, 9, ..., -2] dB
diff --git a/docssource/api/simulation.modem.noise.EBN0.rst b/docssource/api/simulation.modem.noise.EBN0.rst
@@ -0,0 +1,11 @@
+====
+EBN0
+====
+
+.. inheritance-diagram:: hermespy.simulation.modem.noise.EBN0
+
+The bit energy to noise power spectral density ratio (Eb/N0) is a fundamental parameter in digital communication systems.
+It is defined as the ratio of the energy per bit to the noise power spectral density.
+The Eb/N0 is a key parameter in the design of digital communication systems, and is used to determine the minimum signal-to-noise ratio required to achieve a certain bit error rate.
+
+.. autoclass:: hermespy.simulation.modem.noise.EBN0
diff --git a/docssource/api/simulation.modem.noise.ESN0.rst b/docssource/api/simulation.modem.noise.ESN0.rst
@@ -0,0 +1,10 @@
+====
+ESN0
+====
+
+.. inheritance-diagram:: hermespy.simulation.modem.noise.ESN0
+
+The symbol energy to noise power spectral density ratio (ES/N0) is a measure of the signal-to-noise ratio (SNR) in a communication system.
+It is defined as the ratio of the energy per symbol to the noise power spectral density. The ES/N0 is a key parameter in the design of digital communication systems, and is used to determine the required signal-to-noise ratio for a given bit error rate.
+
+.. autoclass:: hermespy.simulation.modem.noise.ESN0
diff --git a/docssource/api/simulation.noise.level.N0.rst b/docssource/api/simulation.noise.level.N0.rst
@@ -0,0 +1,10 @@
+====
+N0
+====
+
+.. inheritance-diagram:: hermespy.simulation.noise.level.N0
+
+The noise level :math:`N_0` representes the expected power of the noise
+in Watts.
+
+.. autoclass:: hermespy.simulation.noise.level.N0
diff --git a/docssource/api/simulation.noise.level.SNR.rst b/docssource/api/simulation.noise.level.SNR.rst
@@ -0,0 +1,11 @@
+====
+SNR
+====
+
+.. inheritance-diagram:: hermespy.simulation.noise.level.SNR
+   :parts: 1
+
+The signal to noise ratio (SNR) is a measure used in science and engineering that compares the level of a desired signal to the level of background noise.
+It is defined as the ratio of signal power to the noise power.
+
+.. autoclass:: hermespy.simulation.noise.level.SNR
diff --git a/docssource/api/simulation.noise.AWGN.rst → ...ource/api/simulation.noise.model.AWGN.rst b/docssource/api/simulation.noise.AWGN.rst → ...ource/api/simulation.noise.model.AWGN.rst
@@ -2,13 +2,13 @@
 AWGN Model
 ==========
 
-.. inheritance-diagram:: hermespy.simulation.noise.noise.AWGN
+.. inheritance-diagram:: hermespy.simulation.noise.model.AWGN
    :parts: 1
 
 Complex additive white Gaussian noise (AWGN) in its circular invariant form is the most common noise model used in communication systems.
 It is a zero mean, white noise process with an independent Gaussian distribution for both real and imaginary part.
 The noise is uncorrelated in time and frequency.
 
-.. autoclass:: hermespy.simulation.noise.noise.AWGN
+.. autoclass:: hermespy.simulation.noise.model.AWGN
 
 .. footbibliography::
diff --git a/.../api/simulation.noise.AWGNRealization.rst → ...imulation.noise.model.AWGNRealization.rst b/.../api/simulation.noise.AWGNRealization.rst → ...imulation.noise.model.AWGNRealization.rst
@@ -2,11 +2,11 @@
 AWGN Realization
 =================
 
-.. inheritance-diagram:: hermespy.simulation.noise.noise.AWGNRealization
+.. inheritance-diagram:: hermespy.simulation.noise.model.AWGNRealization
    :parts: 1
 
 AWGN realizations represent the sampling of the Gaussian distributions associated with additive white Gaussian noise (AWGN).
 
-.. autoclass:: hermespy.simulation.noise.noise.AWGNRealization
+.. autoclass:: hermespy.simulation.noise.model.AWGNRealization
 
 .. footbibliography::