`orbitforge waveform ber`

Synopsis


orbitforge waveform ber [OPTIONS]

Description

Sweeps Es/N0 and measures the bit error rate by simulating the modulator, channel, and demodulator, printing the theoretical curve alongside the measured one.

The theoretical column is what makes this useful. A simulation that tracks theory where theory is valid is a simulation you can trust where it is not, which is the whole point of running one.

Options

Parameter	Type	Unit	Default	Required	Description
`--chain`	string	n/a	`uncoded:qpsk`	No	Chain spec: `uncoded:<mod>`, `conv:<mod>`, or `rs:<mod>`, where the modulation is bpsk, qpsk, 8psk, 16qam, 16apsk, or 32apsk.
`--esn0-db`	string	dB	`0:1:8`	No	Sweep as `start:step:end` inclusive, or a comma-separated list such as `0,2,4`.
`--frame-bits`	integer	bits	`1000`	No	Information bits per frame. Reed-Solomon frames are fixed at 223 bytes.
`--min-errors`	integer	count	`100`	No	Stop a point once this many bit errors have accumulated, checked per batch.
`--max-frames`	integer	count	`10000`	No	Hard cap on frames per point, so a high-Es/N0 point cannot run forever.
`--seed`	integer	n/a	`42`	No	Master seed. Identical seeds reproduce results bit for bit.
`--csv`	path	n/a	—	No	Write the sweep as CSV.
`--json`	path	n/a	—	No	Write the sweep as JSON.

Worked example


orbitforge waveform ber \
  --chain uncoded:qpsk \
  --esn0-db 0:2:8 \
  --frame-bits 1000


Chain uncoded:qpsk (rate 1.0000, 2 bits/symbol, seed 42)
 Es/N0 dB  Eb/N0 dB         bits     errors     frames          BER       theory
     0.00     -3.01        64000      10272         64    1.6050e-1     1.587e-1
     2.00     -1.01        64000       6679         64    1.0436e-1     1.040e-1
     4.00      0.99        64000       3647         64    5.6984e-2     5.650e-2
     6.00      2.99        64000       1496         64    2.3375e-2     2.301e-2
     8.00      4.99        64000        402         64    6.2813e-3     6.004e-3

Reading the output

Column	Meaning
Es/N0 dB	Symbol energy to noise density, the swept variable
Eb/N0 dB	Energy per information bit, derived from Es/N0, code rate, and bits per symbol
bits	Information bits simulated at this point
errors	Bit errors observed
frames	Frames simulated before a stopping condition was met
BER	Measured bit error rate, errors divided by bits
theory	Closed-form prediction for this chain on an AWGN channel

Measured against theory

The two rightmost columns agree to within a few percent at every point, and the agreement is the result worth checking first:

Es/N0	Measured	Theory	Difference
0 dB	1.6050e-1	1.587e-1	1.1 percent
4 dB	5.6984e-2	5.650e-2	0.9 percent
8 dB	6.2813e-3	6.004e-3	4.6 percent

A simulation that matches theory for an uncoded chain is validated. That matters because theory exists only for the simple cases: for a coded chain there is no closed form, and the simulation is the only answer available.

Always run the uncoded case first. If it does not track theory, the coded results from the same code path are not trustworthy either, and the problem is in the harness rather than in the code being evaluated.

The divergence grows at high Es/N0, from 1 percent to 4.6 percent, because fewer errors accumulate. At 8 dB only 402 errors were observed against 10,272 at 0 dB, so the relative statistical uncertainty is roughly five times larger.

Es/N0 and Eb/N0

Both columns describe the same points. Which one to use depends on the question.

\frac{E_b}{N_0} = \frac{E_s}{N_0} - 10\log_{10}\!\left(R \cdot \log_2 M\right)

where $R$ is the code rate and $M$ is the constellation size. For uncoded QPSK, $R = 1$ and $\log_2 M = 2$ , giving a fixed 3.01 dB offset, which is exactly what the two columns show.

Use	Because
Es/N0 for link budgeting	It is what the channel delivers
Eb/N0 for comparing schemes	It normalizes by information rate, so it measures energy efficiency per bit

Stopping conditions and confidence

Each point stops on whichever comes first: --min-errors accumulated, or --max-frames simulated.

--min-errors is the one that governs statistical confidence. Measuring a bit error rate is counting rare events, and the relative uncertainty goes roughly as $1/\sqrt{N}$ in the number of errors. A hundred errors gives about 10 percent relative uncertainty; ten gives about 32 percent.

When a point stops on --max-frames rather than on --min-errors, its error count is below the requested threshold and its BER is correspondingly uncertain. That happens at high Es/N0, where errors are rare, and it is exactly where the interesting operating points live.

Check the errors column. A point with only a handful of errors should not be quoted as a measured bit error rate.

Chains

Spec	Coding	Use
`uncoded:<mod>`	None	Validating the harness against theory
`conv:<mod>`	Convolutional	Legacy and CCSDS-style links
`rs:<mod>`	Reed-Solomon, 223-byte frames	Block-coded links, burst-error resistance

Model basis: Monte Carlo bit-error-rate simulation

Assumptions: Additive white Gaussian noise channel; ideal carrier and symbol timing recovery; no phase noise, non-linearity, or interference; independent bit errors at the demodulator input; theory column from the closed-form expression for the stated modulation on AWGN.
Validity range: Valid for the AWGN assumption. Real links depart from it through amplifier non-linearity, phase noise, and interference, all of which raise the required Es/N0 above these figures.
Accuracy: Statistical, governed by accumulated error count. Roughly 10 percent relative uncertainty at 100 errors, and worse where a point stopped on the frame cap instead. Agreement with theory for uncoded chains is the primary validation.
Reference: Standard closed-form bit-error-rate expressions for coherent detection on AWGN; see Proakis, Digital Communications.

orbitforge waveform ber