`orbitforge waveform thresholds`

Synopsis


orbitforge waveform thresholds --output <PATH> [OPTIONS]

Description

Measures the Es/N0 at which each DVB-S2 modulation and coding scheme actually decodes, by running the real encoder, channel, and decoder over a noise sweep.

The output is not a lookup table copied from a specification. It is a measurement of this implementation, exported as an artifact the link command consumes so that link budgets are quoted against a threshold that was demonstrated rather than assumed.

Options

Parameter	Type	Unit	Default	Required	Description
`--output`	path	n/a	—	Yes	Output JSON artifact path.
`--modcods`	string	n/a	`qpsk-1/2`	No	Comma-separated MODCOD names, for example `qpsk-1/2,8psk-3/4`, or `all`.
`--frame-size`	enum	n/a	`short`	No	`normal` for the 64,800-bit FECFRAME, `short` for 16,200 bits.
`--pilots`	flag	n/a	—	No	Account for pilot blocks in the framing overhead.
`--frames`	integer	count	`20`	No	Frames simulated per Es/N0 grid point. Confidence extends to roughly a packet error rate of 1/N.
`--seed`	integer	n/a	`42`	No	Master seed. The same seed reproduces the same measurement.

Worked example


orbitforge waveform thresholds \
  --modcods qpsk-1/2,8psk-3/4 \
  --frames 10 \
  --output thr.json


qpsk-1/2     Short: Es/N0   1.75 dB, eta 0.849 bit/sym, required Eb/N0   2.46 dB
8psk-3/4     Short: Es/N0   8.00 dB, eta 2.119 bit/sym, required Eb/N0   4.74 dB
Wrote MODCOD threshold artifact -> thr.json

Reading the output

Column	qpsk-1/2	8psk-3/4	Meaning
Es/N0	1.75 dB	8.00 dB	Symbol energy to noise density at which the scheme decodes
eta	0.849 bit/sym	2.119 bit/sym	Spectral efficiency: information bits carried per symbol
Required Eb/N0	2.46 dB	4.74 dB	Energy per information bit to noise density

The trade this table shows

8PSK 3/4 carries 2.5 times the information per symbol as QPSK 1/2, and pays 6.25 dB more Es/N0 for it. That is the fundamental exchange in every link design: throughput against margin.

Which one you can use is decided by the link budget. If the geometry and weather leave 8 dB of Es/N0 at the worst point of the pass, 8PSK 3/4 is available and triples the data rate. If they leave 3 dB, it is not, and pushing it anyway produces a link that works at zenith in clear sky and drops the rest of the time.

Note that Es/N0 and Eb/N0 rank the schemes differently in magnitude: 6.25 dB apart in Es/N0, only 2.28 dB apart in Eb/N0. Eb/N0 normalizes by information rate, so it measures coding efficiency, while Es/N0 measures what the channel must deliver.

Use Es/N0 for link budgeting, because that is what the channel provides. Use Eb/N0 when comparing how efficiently two schemes use energy per bit.

Frames and confidence

--frames sets how many frames are simulated per grid point, and it bounds what the measurement can resolve. With N frames you cannot distinguish packet error rates much below 1/N, because you may simply not have generated an error yet.

`--frames`	Resolves down to roughly	Use
10	1e-1	Quick exploration, as in the example above
20 (default)	5e-2	Routine work
1000 or more	1e-3	A threshold that will be quoted in a design review

The example above uses --frames 10 for speed. A threshold measured over 10 frames is indicative, not quotable. Real operating points are specified at error rates several orders of magnitude lower, and reaching them requires proportionally more frames and substantially more run time.

Frame size and pilots

--frame-size short uses the 16,200-bit FECFRAME; normal uses 64,800 bits. The longer frame gives the code more to work with and lowers the threshold slightly, at the cost of latency and of a larger loss when a frame is lost.

--pilots inserts pilot blocks, which aid carrier recovery on a real receiver but consume capacity. Enabling them lowers effective throughput without changing the decoder threshold, so include the flag if your receiver needs pilots.

Model basis: DVB-S2 MODCOD threshold measurement

Assumptions: Additive white Gaussian noise channel; ideal carrier and timing recovery; the implementation's own LDPC and BCH decoders; thresholds located by simulating a fixed number of frames per Es/N0 grid point.
Validity range: Valid for the AWGN assumption. Real links additionally suffer phase noise, non-linear amplifier distortion, and interference, all of which raise the required Es/N0 above the measured figure.
Accuracy: Bounded by the frame count. With N frames per point, packet error rates below roughly 1/N are unresolved. Measured thresholds are therefore optimistic relative to a specification figure quoted at a much lower error rate.
Reference: ETSI EN 302 307 (DVB-S2), second-generation framing, channel coding and modulation for broadcasting, interactive services and news gathering.

Why measure rather than look up

A published specification quotes the threshold of an ideal implementation. Yours is not ideal. Measuring it produces a number that reflects the decoder you will actually fly, and exporting it into the link budget closes the loop: the margin you quote is margin against demonstrated performance.

The gap between the two is itself informative. A measured threshold far above the specification figure indicates an implementation problem worth investigating before it becomes a link problem.

orbitforge waveform thresholds