Skip to content

Add decibel gain and absolute level types#1

Merged
cleishm merged 2 commits into
mainfrom
decibel-levels
Jul 10, 2026
Merged

Add decibel gain and absolute level types#1
cleishm merged 2 commits into
mainfrom
decibel-levels

Conversation

@cleishm

@cleishm cleishm commented Jul 10, 2026

Copy link
Copy Markdown
Owner

Summary

Adds an opt-in <electro/decibel> header with two types, modeled on the duration/time_point distinction:

  • gain — a dimensionless logarithmic ratio (dB). An ordinary quantity unit: adds, subtracts, negates, scales.
  • level — an absolute point on a logarithmic scale (dBm, dBW, dBV, dBmV, dBµV), parameterized by a reference tag that carries the linear unit, the 0 dB reference precision, the 10·log10 vs 20·log10 factor, and the display symbol.

The affine algebra is enforced at compile time:

auto rx = 20_dBm + 6_dB - 2_dB - 90_dB;  // level ± gain → level: -66 dBm
auto margin = rx - (-100_dBm);           // level − level → gain: 34 dB
// rx + rx;   // ill-formed
// rx * 2;    // ill-formed

Crossing into the linear domain is via explicit named functions — to_linear(30_dBm) is 1000.0 mW, to_level<dbm>(milliwatts(1)) is 0 dBm — the only non-constexpr parts of the header (std::log10/std::pow aren't constexpr until C++26). Combining uncorrelated signals is the explicit add_powers() (10 dBm ⊕ 10 dBm = 13.01 dBm), restricted to power references since summing linear amplitudes on a field reference would model coherent addition instead.

electro.hpp is unchanged; decibels are opt-in so <cmath> and the non-constexpr bridge stay out of the core header.

Version

Bumped to 0.2.0. The vcpkg port SHA512 is reset to the placeholder — it can only be set once the v0.2.0 release tarball is published, mirroring the two-step flow used for v0.1.0.

Testing

  • 21/21 tests pass (Catch2), including ~150 lines of static_assert compile-time checks and concept-based ill-formed-operation tests with positive controls.
  • Every README snippet compile-verified.
  • Local coverage is Apple Clang only; GCC 14 / Clang 17 / MSVC come from CI. Watch the _dBµV literal on MSVC (needs the already-required /utf-8).

cleishm added 2 commits July 9, 2026 23:08
Adds an opt-in <electro/decibel> header with two types, modeled on the
duration/time_point distinction:

- gain: a dimensionless logarithmic ratio (dB), an ordinary quantity
  unit that adds, subtracts, negates, and scales.
- level: an absolute point on a logarithmic scale (dBm, dBW, dBV, dBmV,
  dBµV), parameterized by a reference tag carrying the linear unit, the
  0 dB reference precision, and the 10*log10 vs 20*log10 factor.

The affine algebra is enforced at compile time: level +/- gain -> level
and level - level -> gain, while level + level, level * scalar, and
mixing references are ill-formed. Combining uncorrelated signals is the
explicit add_powers() (10 dBm + 10 dBm = 13.01 dBm), restricted to
power references.

Crossing between the logarithmic and linear domains is via explicit
named functions (to_linear, to_level, power_ratio, amplitude_ratio,
power_gain, amplitude_gain), which are the only non-constexpr parts of
the header (std::log10/std::pow are not constexpr until C++26).

Decibels opt out of the SI-prefix suffix machinery; precisions render
as fixed-point decimals ("13.01dBm", never "1301cdBm"). Literals cover
_dB, _cdB, _dBm, _cdBm, _dBW, _dBV, _dBmV, _dBuV, and _dBµV.

The core electro.hpp header is unchanged.
The vcpkg port SHA512 is reset to the placeholder; it can only be set
once the v0.2.0 release tarball is published, as was done for v0.1.0.
@cleishm
cleishm merged commit 68e3945 into main Jul 10, 2026
6 checks passed
@cleishm
cleishm deleted the decibel-levels branch July 10, 2026 03:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant