antopoid/Python-Shannon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add interactive exploration of Shannon's capacity formula with Plotly graphs
All checks were successful
Build & Deploy Shannon / 🏗️ Build & Deploy Shannon (push) Successful in 3m1s
Details

Browse Source 
- Implemented bandwidth sensitivity and power sensitivity plots.
- Created a contour map for bit rate multiplying factors.
- Added input parameters for C/N and bandwidth with validation.
- Displayed computed results and sensitivity analysis metrics.
- Integrated interactive graphs for user exploration.
- Included background information section for user guidance.
This commit is contained in:
Poidevin, Antoine (ITOP CM) - AF
2026-02-20 10:33:09 +01:00
parent beda405953
commit 6a4ccc3376
38 changed files with 4319 additions and 11161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
core/help_texts.py Normal file
View File

@@ -0,0 +1,297 @@
"""
Help texts for Shannon application.
Cleaned-up version of Shannon_Dict.py, organized by section.
Unicode subscripts/superscripts replaced by readable equivalents for web display.
"""
# ──────────────────────────────────────────────────────────────────────────────
# Panel 1: Theoretical Exploration
# ──────────────────────────────────────────────────────────────────────────────
THEORY_HELP = {
"cnr": (
"**Reference C/N [dB]**\n\n"
"Reference Carrier to Noise Ratio in decibels: 10·log(C/N), where C is the "
"Carrier's power and N is the Noise's Power, both measured in the reference "
"Channel Bandwidth.\n\n"
"The Carrier's power is often named Signal's Power and the Carrier to Noise Ratio "
"is often named Signal to Noise Ratio."
),
"bw": (
"**Reference BW [MHz]**\n\n"
"Reference Channel Bandwidth — a key parameter of the communication channel.\n\n"
"This bandwidth is usually a degree of freedom of the system design, eventually "
"constrained by technological constraints and various kinds of frequency usage regulations."
),
"c_n0": (
"**Carrier Power to Noise Power Density Ratio: C/N₀**\n\n"
"Carrier's power (in Watts) divided by the Noise Spectral Power Density "
"(in Watts per MHz). The result's units are MHz."
),
"br_inf": (
"**Theoretical BR at infinite BW: 1.44·C/N₀**\n\n"
"Bit Rate theoretically achievable when the signal occupies an infinite Bandwidth. "
"This value is a useful asymptotic limit."
),
"br_unit": (
"**Theoretical BR at Spectral Efficiency = 1: C/N₀**\n\n"
"Bit Rate theoretically achievable at a Spectral Efficiency = 1: "
"Bit Rate in Mbps = Bandwidth in MHz.\n\n"
"The corresponding value, deduced from Shannon's formula, is given by C/N₀."
),
"br_bw": (
"**Theoretical BR at Reference (BW, C/N)**\n\n"
"Bit Rate theoretically achievable when the Bandwidth is constrained "
"to the given reference value."
),
"cnr_lin": (
"**C/N = C / (N₀·B)**\n\n"
"Reference Carrier to Noise Ratio (or Signal to Noise Ratio). "
"The C/N Ratio is usually given in dB: 10·log(C/N).\n\n"
"Although the logarithm is convenient for many evaluations (multiplications become additions), "
"it's also good to consider the ratio itself (Linear Format) to get some physical sense "
"of the power ratio.\n\n"
"The Carrier to Noise Ratio in linear format is the value used in Shannon's formula."
),
"br_mul": (
"**Bit Rate Increase Factor**\n\n"
"Bit Rate multiplying factor achieved when the Bandwidth and the Power "
"are multiplied by a given set of values."
),
"bw_mul": (
"**BW Increase Factor**\n\n"
"Arbitrary multiplying factor applied to the Carrier's Bandwidth, for sensitivity analysis."
),
"p_mul": (
"**Power Increase Factor**\n\n"
"Arbitrary multiplying factor applied to the Carrier's Power, for sensitivity analysis."
),
"shannon": (
"**The Shannon Limit** allows to evaluate the theoretical capacity achievable over "
"a communication channel.\n\n"
"As a true genius, Claude Shannon founded communication theory, information theory "
"and more (click the Wikipedia button for more info).\n\n"
"This equation is fundamental for the evaluation of communication systems. "
"It is an apparently simple but extremely powerful tool to guide communication systems' designs.\n\n"
"This equation tells us what is achievable, not how to achieve it. It took almost 50 years "
"to approach this limit with the invention of Turbo codes.\n\n"
"In the satellite domain, DVB-S2x, using LDPC codes iteratively decoded (Turbo-Like), "
"is only 1 dB away from this limit."
),
"advanced": (
"**AWGN Channel Model**\n\n"
"The model assumes that the communication channel is **AWGN** (Additive White Gaussian Noise). "
"This noise is supposed to be random and white, meaning noise at a given time is independent "
"of noise at any other time — implying a flat and infinite spectrum. "
"This noise is also supposed to be Gaussian.\n\n"
"Although these assumptions seem very strong, they accurately match the cases of interest. "
"Many impairments are actually non-linear and/or non-additive, but combining equivalent C/N "
"of all impairments as if they were fully AWGN is in most cases very accurate. "
"The reason is that the sum of random variables of unknown laws always tends to Gaussian, "
"and thermal noise is dominating, actually white and gaussian, and whitening the rest.\n\n"
"The tool accepts lists of comma-separated CNRs which will be combined in that way.\n\n"
"Overall, the Shannon Limit is a pretty convenient tool to predict the real performances "
"of communication systems."
),
"help": (
"**Recommendations for using the tool**\n\n"
"The first purpose of the tool is educational, allowing people to better understand "
"the physics of communications and the role of key parameters.\n\n"
"- Try multiple values in all the fields one by one\n"
"- Explore the graphs and try to understand the underlying physics\n"
"- The units are as explicit as possible to facilitate the exploration\n"
"- Click on the ℹ️ icons to get information about each parameter"
),
}
# ──────────────────────────────────────────────────────────────────────────────
# Panel 2: Real World (Satellite Link Budget)
# ──────────────────────────────────────────────────────────────────────────────
REAL_WORLD_HELP = {
"freq": (
"**Frequency [GHz]**\n\n"
"Frequency of the electromagnetic wave supporting the communication.\n\n"
"For satellite downlink, typical bands: L: 1.5 GHz, S: 2.2 GHz, C: 4 GHz, "
"Ku: 12 GHz, Ka: 19 GHz, Q: 40 GHz"
),
"sat_alt": (
"**Satellite Altitude [km]**\n\n"
"The position of the satellite is expressed in latitude, longitude, altitude. "
"A GEO satellite has a latitude of 0° and an altitude of 35786 km. "
"LEO satellites have altitudes lower than 2000 km. "
"MEO altitudes are between LEO and GEO (O3B constellation: 8063 km)."
),
"sat_latlon": (
"**Satellite Latitude and Longitude [°]**\n\n"
"The program doesn't simulate the orbit — any satellite coordinates can be used. "
"A GEO satellite has a latitude of 0°."
),
"gs_latlon": (
"**Ground Station Lat, Lon [°]**\n\n"
"The position of the ground station affects link availability due to weather statistics "
"(tropical regions have very heavy rains attenuating signals at high frequencies). "
"It also impacts the elevation angle and overall path length.\n\n"
"🔗 [Find coordinates](https://www.gps-coordinates.net)"
),
"availability": (
"**Link Availability [%]**\n\n"
"A high desired link availability corresponds to high signal attenuation: "
"only rare and severe weather events exceeding this attenuation can interrupt the link.\n\n"
"For example, at 99.9% availability, the attenuation considered is only exceeded 0.1% of the time."
),
"path_length": (
"**Path Length [km] @ Elevation [°]**\n\n"
"Distance from the satellite to the ground station and elevation angle. "
"Minimum path length = satellite altitude (elevation = 90°). "
"A negative elevation means the satellite is not visible."
),
"atm_loss": (
"**Atmospheric Attenuation [dB]**\n\n"
"The atmosphere affects radio wave propagation with attenuation from rain, clouds, "
"scintillation, multi-path, sand/dust storms, and atmospheric gases.\n\n"
"Typical attenuation exceeded 0.1% of the time in Europe from GEO:\n"
"- Ku: 2.5 dB\n- Ka: 6.9 dB\n- Q: 22 dB\n\n"
"Uses [ITU-Rpy](https://itu-rpy.readthedocs.io/en/latest/index.html)."
),
"hpa": (
"**HPA Output Power [W]**\n\n"
"Power of the High Power Amplifier at the satellite's last amplification stage. "
"Some satellites operate at saturation (DTH), others in multicarrier mode with "
"reduced power (3 dB Output Back Off is typical for VSAT)."
),
"sat_beam": (
"**Satellite Beam Diameter [°]**\n\n"
"Half-power beam width. Typical values: 0.4–1.4° for GEO HTS, 3–6° for GEO DTH."
),
"gain_offset": (
"**Gain Offset from Peak [dB]**\n\n"
"Simulates terminals not at beam peak. 3 dB = worst case in 3 dB beam (DTH). "
"1 dB = typical median performance for single feed per beam HTS."
),
"losses": (
"**Output Section Losses [dB]**\n\n"
"Signal loss between HPA and antenna (filters, waveguides, switches). "
"Typical: 2.5 dB for classical satellites, 1 dB for active antennas."
),
"sat_cir": (
"**Satellite C/I [dB]**\n\n"
"Signal impairments from satellite implementation: intermodulation, filtering, phase noise. "
"Supports comma-separated lists to include uplink C/N, interferences, etc."
),
"output_power": "**Output Power [W]** — Signal power at antenna output carrying user information.",
"sat_gain": (
"**Satellite Antenna Gain**\n\n"
"Ratio between signal radiated on-axis vs. isotropic antenna. "
"Expressed in dBi (dB relative to isotropic antenna)."
),
"eirp": (
"**Equivalent Isotropic Radiated Power (EIRP)**\n\n"
"Product Power × Gain in Watts. Represents the power required for an isotropic antenna "
"to match the directive antenna's radiation in that direction."
),
"path_loss": (
"**Path Dispersion Loss**\n\n"
"Free-space propagation loss — simply the surface of a sphere with radius = path length. "
"Not actual absorption, just geometric spreading."
),
"pfd": (
"**Power Flux Density**\n\n"
"Signal power per square meter at the terminal side. "
"Actual captured power = PFD × antenna effective area."
),
"cpe_ant": (
"**Customer Antenna Size [m]**\n\n"
"Parabolic antenna with state-of-the-art efficiency (~60%)."
),
"cpe_temp": (
"**Noise Temperature [K]**\n\n"
"Total receiver's clear-sky noise temperature. Includes all contributors: "
"receiver, sky, ground seen by antenna. Default of 120 K is a reasonable typical value."
),
"cpe_gain": (
"**Antenna Effective Area and G/T**\n\n"
"G/T is the figure of merit of a receive antenna: Gain / Noise Temperature. "
"In case of rain, the signal is punished twice: attenuation weakens it and "
"the rain attenuator generates additional noise."
),
"rx_power": "**RX Power** — Extremely small power before amplification. This is 'C' in Shannon's equation.",
"n0": "**Noise Power Density N₀** — Noise Spectral Power Density of the radio front end.",
"br_inf": (
"**Bit Rate at infinite BW** — Asymptotic limit: 1.443·C/N₀. Never achieved in practice."
),
"br_unit": "**Bit Rate at Spectral Efficiency=1** — Bandwidth = Bit Rate and C/N = 0 dB.",
"br_double": (
"**Bit Rate at Spectral Efficiency=2** — Bandwidth-efficient operating point "
"(BW = 0.5 × BR), often considered typical."
),
"bandwidth": (
"**Occupied Bandwidth [MHz]**\n\n"
"Bandwidth occupied by the communication channel — a key degree of freedom in system design."
),
"rolloff": (
"**Nyquist Filter Rolloff [%]**\n\n"
"Excess bandwidth required beyond the theoretical Nyquist minimum. "
"The Nyquist filter avoids inter-symbol interference."
),
"cir": (
"**Receiver C/I [dB]**\n\n"
"Signal impairments from terminal: phase noise, quantization, synchronization errors. "
"Supports comma-separated lists."
),
"penalty": (
"**Implementation Penalty [dB]**\n\n"
"DVB-S2x with LDPC codes is typically 1 dB from Shannon Limit. "
"With 0.5 dB margin, a total of 1.5 dB is typical."
),
"overhead": (
"**Higher Layers Overhead [%]**\n\n"
"Encapsulation cost (IP over DVB-S2x via GSE). Typically ~5% for modern systems."
),
"cnr_bw": "**SNR in Available BW** — Signal-to-Noise Ratio in the available bandwidth.",
"cnr_nyq": "**SNR in Nyquist BW** — SNR in Nyquist BW = Available BW / (1 + Roll-Off).",
"cnr_rcv": (
"**SNR at Receiver Output** — Combining link noise, satellite C/I, and receiver C/I. "
"This is the relevant ratio for real-life performance."
),
"br_nyq": (
"**Theoretical Bit Rate** — Direct application of Shannon Limit in Nyquist BW. "
"Efficiency in bits/symbol also shown."
),
"br_rcv": (
"**Practical Physical Layer Bit Rate** — Using all-degradations-included SNR "
"in Shannon's formula."
),
"br_high": (
"**Practical Higher Layers Bit Rate** — Corresponds to user bits of IP datagrams."
),
"satellite": (
"The evaluation is decomposed in 3 sections:\n\n"
"1. **Satellite Link** — transmitter and path to receiver with key characteristics\n"
"2. **Radio Front End** — antenna and amplification capturing signal with minimal noise\n"
"3. **Baseband Unit** — digital signal processing: filtering, synchronization, "
"demodulation, error correction, decapsulation\n\n"
"All fields are initially filled with meaningful values. Start by changing the "
"straightforward parameters. All parameters have help tooltips."
),
"advanced": (
"**Advanced Analysis Notes**\n\n"
"All capacity evaluations use direct application of the Shannon formula with real-world "
"impairments via C/N combinations. Useful links:\n\n"
"- [Nyquist ISI Criterion](https://en.wikipedia.org/wiki/Nyquist_ISI_criterion)\n"
"- [Error Correction Codes](https://en.wikipedia.org/wiki/Error_correction_code)\n"
"- [Viterbi Decoder](https://en.wikipedia.org/wiki/Viterbi_decoder)\n"
"- [Turbo Codes](https://en.wikipedia.org/wiki/Turbo_code)\n"
"- [DVB-S2](https://en.wikipedia.org/wiki/DVB-S2)\n"
"- [OSI Model](https://en.wikipedia.org/wiki/OSI_model)"
),
"help": (
"**Recommendations**\n\n"
"- Try multiple values one by one, starting from the least intimidating\n"
"- Explore the graphs to understand the physics\n"
"- Units are as explicit as possible\n"
"- The tool can also be used for a quick first-order link analysis"
),
}