phase-locked-loop
The Rate, Pacer, complete Follower and pllpace command are implemented.
Version 0.1.0.
This library helps audio/video, sensor, packet and device-buffer applications pace units on their own timeline or learn the relationship to another clock. A rational Pacer issues numbered slots without accumulated rounding drift. A type-II, second-order phase-locked Follower estimates remote-clock phase and frequency, filters delivery jitter, and maps ticks to local nanoseconds. They work separately or together: follower trim can steer a pacer.
Provenance, parity and non-goals
Source: Go github.com/version2beta/pll, revision
971282632129110794c9d6edd22026e9de2359be. The basis is its complete SPEC.md, README.md,
rate.go, pacer.go, span.go, follower.go, errors/status/package comments,
and the rate, pacer, follower, examples, boundary and differential-model tests.
The original is provenance, not a runtime dependency.
Functional parity means exact pacer results, equivalent follower equations and state transitions, error categories and atomic failures on the shared domain. It does not mean Go ABI, duration formatting, writable span fields, iterator protocol, zero-value controller structs, sentinel-error matching, memory layout, or Go-specific arithmetic fast paths. Python representations are specified here. There is no transplanted claim about Go nanosecond benchmarks, zero allocations, race-detector results, simulator results or real-time scheduling.
This is a library, not a token bucket, sleeping rate limiter, scheduler, clock
servo/PTP/NTP client, counter-unwrapper, transport, payload queue or device driver.
The Go cmd/pllpace, cmd/pllsim, UDP tests, full simulator and benchmarking
commands were excluded from initial port scope. The
pllpace adapter is included; simulator and benchmark products remain deferred.
Installation
Requires CPython 3.11+ with binary64 floats and unbounded integers.
No runtime dependencies. The distribution is phase-locked-loop; the import is pll.
After the 0.1.0 release is published:
python -m pip install phase-locked-loop==0.1.0
For a release candidate, install the validated wheel with
python -m pip install --no-index --no-deps WHEEL_PATH.
pllpace is the sole console entry point.
Real-time pacing command (pllpace)
After local wheel installation, run pllpace --help, or use
python -m pll.pllpace (also available from this source checkout):
pllpace -seconds 0.1 -bps 8000 -unit-bytes 1000
python -m pll.pllpace --mode ticker --seconds 0.1 --bps 8000
pllpace -seconds 0.1 -bps 8000 -udp loopback -per-datagram 2
# Optional longer measurement; sends only to an in-process localhost receiver:
pllpace -find-max -seconds 2 -udp loopback -slack 5ms
Shares upstream cmd/pllpace option defaults (timing differences below): 100,000,000 bits/s,
1000 bytes/unit, 10 seconds/trial, pacer mode, discard output, one unit per
UDP datagram, search disabled, and 5ms search slack. Both -flag and --flag
forms (including =value) work. -find-max is a presence-only argparse flag,
not Go's -find-max=true/false; omit it for false. Argparse rejects positional
arguments/unknown options and uses exit 2 for syntax errors; semantic/runtime
errors use exit 1, interruption 130. Slack accepts signed composite Go-style
ns, us/µs/μs, ms, s, m, h durations (or 0); seconds is a
finite floating-point count converted to integer ns. Source uint64/int64 and
platform-int envelopes and the 65507-byte UDP payload limit are retained.
All options are validated before payload allocation or sockets are opened.
Pacer mode uses Pacer(bits_per_second(...)), slot zero immediately due,
and batches at most 4096 units per wake-up without dropping backlog. Ticker
mode starts after one exact integer-ns period and emits one unit per wake-up,
dropping missed periods; it is a Python monotonic-clock/sleep comparison,
not Go's timer implementation or a real-time scheduler guarantee. Sleeps
are capped at the trial deadline, even at very low rates. Final partial groups
are flushed per trial, including flush time in elapsed/backlog/byte counts;
failed writes discard buffered data, never retry it in the next trial.
Discard ignores -per-datagram, matching upstream. UDP is used only with
-udp loopback or -udp host:port (bracket IPv6 addresses); remote destinations
are resolved/sent to only when explicitly selected. The localhost receiver and
sender are closed and the worker joined on success, error or interruption.
UDP writer acceptance does not acknowledge delivery; receipt is not measured.
Output includes progress each elapsed second, writer Mbps, offered units,
writer-accepted bytes, elapsed time, end backlog, wake-up count/average/max
batch, and pacer oldest-unit lateness median/p99/max (floor-index quantiles).
Durations are printed in milliseconds rather than Go duration formatting.
Search trials must be nonempty, have end backlog <= slack and lateness p99 <=
slack; rates double from -bps through at most 1,000,000,000,000 bits/s, then
bisect a passing/failing bracket until within 5% or adjacent integer rates.
If the initial rate fails it does not search below it. If all doubling trials
pass, only the highest tested rate is reported. This is an empirical local
measurement, not proof of a globally maximal sustainable rate or portable
performance. Trial duration, byte allocations and collected lateness samples
consume real time/memory; search can run many trials. Ctrl-C cancels it.
The library itself still performs no implicit effects. Importing pll.pllpace
starts no clocks, output, threads or sockets; effects belong to CLI invocation.
First useful example
All times are integer nanoseconds, never floating seconds or datetime.
from pll import Pacer, units_per_second
p = Pacer(units_per_second(48_000, 1))
rows = []
for now_ns in (0, 10_000_000, 25_000_000):
span = p.due(now_ns, 4096)
rows.append((span.first, span.count))
assert rows == [(0, 1), (1, 480), (481, 720)]
assert p.next_due() == (1201, 25_020_834)
At 10 ms, slot 480 is exactly due; slot zero was already consumed. At 25 ms,
slot 1200 is due. Slot 1201 has exact time 1201 * 10**9 / 48000, whose
ceiling is 25,020,834 ns. A late call produces backlog rather than silently
losing work. The caller chooses to process it, cap each batch, or skip it.
Public API
Signatures use ordinary Python annotations; Iterator is from collections.abc.
Methods not shown as properties are called methods. No async or blocking API.
| API | Result / meaning |
|---|---|
units_per_second(num: int, den: int) -> Rate |
Reduce by gcd; zero terms raise InvalidRateError. |
bits_per_second(bits: int, bits_per_unit: int) -> Rate |
Exactly the same fraction, bits/bits per unit. |
Rate() |
Immutable invalid zero sentinel, num == den == 0; factories create valid rates. Other direct constructor arguments are unsupported. |
Rate.num: int, Rate.den: int |
Read-only reduced terms. |
str(rate) |
"48000 units/s", "30000/1001 units/s", or "invalid rate". |
Pacer(rate: Rate) |
Mutable owned controller, cursor 0, trim 0; invalid rate raises InvalidRateError. |
p.due(now_ns: int, max_count: int) -> Span |
Oldest due slots up to cap; advances cursor. |
p.claim(n: int) -> Span |
Next n slots, due or not; advances cursor. |
p.skip(now_ns: int, keep: int) -> int |
Skip oldest due slots except newest keep; returns skipped count. |
p.next_due() -> tuple[int, int] |
(cursor_slot, first_due_ns), no mutation. |
p.set_trim(ppt: int) -> None |
Change timing from cursor. |
p.trim() -> int |
Current parts-per-trillion trim. |
Span() |
Immutable empty zero span (first == count == 0). Other direct construction unsupported. |
span.first: int, span.count: int |
Read-only issued extent. |
span.time(i: int) -> int |
Floored time of relative index i; IndexError for i < 0 or i >= count. No negative indexing. |
span.all() -> Iterator[tuple[int, int]] |
Fresh lazy iterator of (slot, time_ns); early stop does not compute remaining items. |
default_follower_config(nominal: Rate) -> FollowerConfig |
Frozen dataclass value with defaults below; does not validate the nominal rate. |
FollowerConfig(...) |
Frozen dataclass with all ten required fields below, no hidden defaults; use the default factory and dataclasses.replace. Validation is at Follower construction. |
Follower(config: FollowerConfig) |
Mutable owned controller; validates config and snapshots it, initially unanchored. |
f.observe(local_ns: int, remote: int) -> Observation |
Feed reading; mutate only on successful return. |
f.local(remote: int) -> int |
Remote ticks to local ns. |
f.remote(local_ns: int) -> int |
Local ns to remote ticks. |
f.offset() -> float, f.trim() -> int, f.jitter() -> int |
Fractional rate offset, pacer-compatible ppt, RMS error ns. |
f.state(now_ns: int) -> State |
Pure query using supplied now. |
f.reset() -> None |
Clear all learned/history state; retain validated configuration. |
Observation.status: Status, Observation.error_ns: int |
Frozen dataclass; phase error, not an exception. |
Status is an enum.IntEnum: ANCHORED=1, ACCEPTED=2, PENDING=3,
REJECTED=4, STEPPED=5. str() is respectively anchored, accepted,
pending, rejected, stepped. State is an IntEnum: ACQUIRING=0,
LOCKED=1, HOLDOVER=2, with corresponding lowercase strings. For Go's
unknown-value string behavior, constructing either enum with any other byte
integer 0..255 is permitted as an unnamed value: str(Status(9)) == "Status(9)"
and str(State(9)) == "State(9)". Unknown statuses are never emitted by the
library. Values outside the byte domain raise ValueError. Bool and non-int construction
raise TypeError, even if numerically equal to a member; int subclasses are accepted.
Types, bounds and exceptions
These envelopes are deliberate compatibility constraints despite Python's
unbounded integers. Let U = 2**64 - 1, Imin = -2**63, Imax = 2**63 - 1.
Rate terms and slot/count/cap/keep arguments are integers in 0..U; valid rate
terms and claim/cap counts must be positive. Pacer times supplied by the caller
must fit signed 64-bit ns, then must be nonnegative. Follower local/now times
and remote ticks may be negative but must fit signed 64-bit. Config duration
fields fit signed 64-bit; step/lock counts also use signed 64-bit (the
64-bit compatibility baseline, rather than a platform-dependent Go int).
Trim inputs fit signed 64-bit, then must lie strictly between ±10**12.
Internal intermediate integer products are unbounded and must not overflow.
Validation checks all argument types, then all input envelopes, then
semantics; within each phase use signature order. Wrong object/type arguments
raise TypeError; bool is rejected. int subclasses are accepted for integer
arguments; float subclasses are accepted where float is required. The three
float config fields require Python float, not integer coercion. Config
retains the field-by-field exception below. Thus units_per_second(-1, "x")
raises TypeError, while units_per_second(0, 2**64) and due(-1, 2**64) raise
OverflowError before zero/negative semantic errors. An integer outside its input envelope
raises OverflowError (the built-in), distinct from a computed-result
PllOverflowError. Within-envelope zero rate terms raise InvalidRateError;
negative pacer time, zero count/cap or trim outside its open interval raise
InvalidArgumentError. Negative unsigned inputs are outside the input envelope,
not silently wrapped. Span indexing uses IndexError for any integer outside
0..count-1; non-integers raise TypeError.
All domain errors derive from exported PllError(Exception), with .code:
| Exception | code | str(exception) |
|---|---|---|
InvalidRateError |
invalid_rate |
pll: invalid rate |
InvalidArgumentError |
invalid_argument |
pll: invalid argument |
PllOverflowError |
overflow |
pll: overflow |
OrderError |
order |
pll: reading out of order |
NotAnchoredError |
not_anchored |
pll: follower has no reading yet |
ConfigError |
config |
pll: FollowerConfig.<field> <reason> |
ConfigError has read-only .field: str (the snake-case field below) and
.reason: str; other errors have no field/reason attributes promised. Config
validation is in table order: each field's type/envelope is checked, then its
semantic rule, before proceeding to the next field. Wrong config field types
or envelopes produce the corresponding built-in error; validly typed but
semantically invalid fields produce ConfigError. This adds a Python boundary
to Go's statically typed domain. Catch by class/code, not message parsing.
Every failed public operation preserves the supplied state, including order, windows, outlier runs, jitter and issued spans; no partial controller mutation or partial result is returned. This includes built-in validation exceptions. Rejected and pending observations are successful results, not failed calls. Controller constructors that fail do not expose a partly initialized object.
Exact pacer contract
Slots start at 0; the cursor is the next slot neither issued nor skipped. It
never decreases. Slot U is never issued or skipped; cursor U is permitted,
so first + count <= U. The nominal rate is the reduced num/den units/s.
A segment has start slot S, integer anchor A ns and trim q ppt:
T(s) = A + (s-S) * den * 10^21 / (num * (10^12 + q)), s >= S
initially S=0, A=0, q=0
Compute with exact integer/rational arithmetic, including extreme terms and
q = ±(1012-1). The period may be reduced once, but no Go fast-path layout is
required. Span.time is floor(T); a slot is due only if exact T <= now.
Thus at period 8/3 ns, time(1) is 2 but it first becomes due at 3.
At rates above 109, times may repeat and remain non-decreasing.
- due: negative now or zero cap is invalid. Find the largest due slot L
exactly (cap L at U). If none at/after cursor is due, return an empty span
with
first=cursor, without advancing. If cursor U itself is due, overflow; otherwise issue cursor through min(L,U-1), capped by max_count, oldest first. Earlier now values are allowed and may still drain their due backlog. - claim: zero n is invalid. Overflow if n > U-cursor, or the last slot's floored time exceeds Imax; otherwise issue and advance, regardless of now.
- skip: D is the number due could issue ignoring its cap (excluding U). Advance by D-min(D,keep); keep=0 skips all available due slots. Negative now is invalid; cursor U with that slot due overflows, even if keep would retain it. With k>0, skip(now,k) then due(now,k) issues the newest k available due slots (or all if fewer). With k=0 do not call due with a zero cap.
- next_due: return cursor and ceil(T(cursor)). Overflow if cursor U or the ceiling exceeds Imax. A floor can fit when the ceiling does not.
- set_trim: reject q <= -1012 or q >= 1012. If q equals current trim, do nothing, even if the cursor time cannot fit. Otherwise compute S=cursor, A=floor(T_old(cursor)), q=new trim; overflow if A>Imax. The new anchor moves phase earlier by less than 1 ns, maintains non-decreasing times, and prevents accumulating fractional anchors. Existing spans retain their original timing independently of future trims.
An issued span is immutable and self-contained for timing, covers first through first+count-1, and may outlive its pacer. Empty spans iterate zero items and have no valid time index. Manually forged objects/private-field changes have no timing guarantees. No operation materializes every slot merely to issue a span.
More hand-checkable pacing examples
from pll import Pacer, bits_per_second, units_per_second
r = units_per_second(60_000, 2002)
assert (r.num, r.den, str(r)) == (30_000, 1001, "30000/1001 units/s")
p = Pacer(r)
assert list(p.claim(4).all()) == [
(0, 0), (1, 33_366_666), (2, 66_733_333), (3, 100_100_000)
]
byte_pacer = Pacer(bits_per_second(50_000_000, 8))
assert [byte_pacer.claim(n).time(0) for n in (1500, 400, 1500)] == [0, 240_000, 304_000]
p = Pacer(units_per_second(1000, 1))
assert p.skip(10_000_000, 3) == 8 # slots 0..10 due, keep 8..10
old = p.due(10_000_000, 3)
assert list(old.all()) == [(8, 8_000_000), (9, 9_000_000), (10, 10_000_000)]
p.set_trim(-500_000_000_000) # half speed, anchored at slot 11 / 11 ms
assert list(p.claim(3).all()) == [(11, 11_000_000), (12, 13_000_000), (13, 15_000_000)]
assert old.time(2) == 10_000_000
Boundary fixture: rate (2_000_000_000, U) has period Imax + 1/2 ns.
After claiming slot 0, next_due overflows, due(Imax,1) is empty at first=1,
but claim(1) succeeds with time Imax. At rate (U,1), claim(U) reaches cursor
U; due(0,1) is empty but due(109,1), skip(109,0), claim(1) and next_due
all overflow. These must remain cheap span operations, not enormous iterations.
Follower configuration (all defaults and validation)
Start from default_follower_config(rate) and use dataclasses.replace.
There is no live config mutation; construct a new follower to change settings.
The table order is the validation order; reasons are exact strings.
| Python field (Go field) | Type | Default | Invalid when / ConfigError reason |
|---|---|---|---|
nominal (Nominal) |
Rate | supplied rate | zero/invalid rate: must be a valid Rate |
bandwidth_hz (Bandwidth) |
float | 0.1 | nonfinite or <=0: must be finite and > 0 |
damping (Damping) |
float | sqrt(2)/2 | nonfinite or <=0: must be finite and > 0 |
max_offset_ppm (MaxOffsetPPM) |
float | 500.0 | nonfinite, <=0 or >=1000000: must be finite, > 0 and < 1000000 |
window_ns (Window) |
int | 0 | <0: must be >= 0 |
outlier_threshold_ns (OutlierThreshold) |
int | 5_000_000 | <=0: must be > 0 |
step_after (StepAfter) |
int | 3 | <1: must be >= 1 |
lock_threshold_ns (LockThreshold) |
int | 100_000 | <0: must be >= 0 |
lock_count (LockCount) |
int | 8 | <1: must be >= 1 |
holdover_after_ns (HoldoverAfter) |
int | 5_000_000_000 | <=0: must be > 0 |
Defaults target low-jitter readings. An optional, not automatic, network profile from the source uses bandwidth 0.005 Hz, window 1_000_000_000 ns, lock threshold 2_000_000 ns, outlier threshold 20_000_000 ns, other defaults unchanged. It trades settling speed for filtering. No source simulator's measured accuracy or lock latency is promised by this library.
Follower state machine and numerical contract
Local times use a caller-chosen origin, possibly negative; remote is an already
unwrapped signed tick counter. Nominal tick period Pn = float(den)*1e9/float(num)
is binary64 ns. Hold anchor as integer I0 plus binary64 fraction frac, remote
anchor R0, and offset y. Initially unanchored, y=0, jitter=0, acquiring.
displacement(r) = ((ticks*Pn)/(1+y)) + frac
e = nanos_between(local,I0) - displacement(r)
remote speed = nominal * (1+y)
Here ticks=nanos_between(r,R0): this helper subtracts integers before conversion when signed64 fits, otherwise subtracts the separately converted float operands. Never form absolute predicted time as a float. Pn=(float(den)1e9)/float(num), wn=(2pi)bandwidth; preserve these groupings and the gain groupings below, without FMA/reassociation. remote uses ((ns-frac)(1+y))/Pn. Positive infinite products are permitted only before the x/kp min caps. Do not compute 2*damping before multiplying x, nor cap dt before multiplying wn.
Compute integer differences before converting to float when they fit signed
64-bit, preserving small differences at huge absolute times. If a difference
exceeds signed 64-bit, use float(a)-float(b) as in Go; do not wrap or round the
integer anchor itself to float. Converting a large difference to float can
still lose low bits beyond 2**53. Rebase on every loop update using integer plus
fraction anchors so precision does not depend on absolute local uptime.
observe, in order
- After the first reading, local must be >= the last successful reading's
local, and remote strictly greater than its remote. Otherwise
OrderError. Previous includes pending/rejected/stepped readings, not failed calls. - First reading (also after reset) anchors exactly to
(local,remote), offset zero, clears histories, and returnsObservation(Status.ANCHORED, 0). - With window_ns=0 feed each later reading as a sample. With window_ns>0, the first later reading opens a window at its local time, becomes candidate and returns pending with error_ns=0. Within the half-open window, replace the candidate only for a strictly smaller signed phase error, not smaller absolute error. Ties retain the earlier candidate. Loop mapping stays fixed.
- At elapsed local >= window_ns, feed the old candidate, return its result, then open the next window with the triggering reading. Compute the new candidate error against the mapping after the flush. Window boundaries use exact elapsed comparison even across the signed-time range; do not overflow start+window. No timer/flush API exists: the final pending candidate is not fed without another boundary reading. Returned phase error and last accepted time belong to the candidate, not necessarily the triggering input.
- If feeding would overflow the integer local anchor, raise PllOverflowError and commit nothing, including the triggering reading, candidate replacement, order coordinates or an earlier outlier run.
Feeding a sample
Let e be its unrounded binary64 phase error in ns.
-
If abs(e)>outlier_threshold_ns, it is an outlier. A run continues only when abs(e-e_first)<=threshold, measured against the first error of the run; otherwise start a new run of length 1. On reaching step_after, re-anchor exactly to the fed sample, keep y, clear lock/jitter/outlier run, record the sample local as last accepted and return stepped. Otherwise return rejected: mapping, lock, jitter and last accepted do not change, but outlier metadata and successful-input order do. An inlier ends the run only on successful feed.
-
For an inlier let dt be local seconds since last anchor/step/loop update. If dt>0, compute using the old mapping:
wn = 2*pi*bandwidth_hz x = min(0.5, wn*dt) kp = min(1, 2*(damping*x)) y_new = clamp(y - (x*x/dt)*e/1e9, -max_offset_ppm*1e-6, +max_offset_ppm*1e-6) v = displacement_old(remote) + kp*e whole = round_away(v) I0_new = I0 + whole; frac_new = v-whole; R0_new = remote
Check I0_new against signed 64-bit before committing; set the update reference time to sample local. The capped product is essential for sparse readings and extreme finite gains; avoid overflow/NaN intermediates changing the capped result. In particular do not evaluate
Inf*0by capping dt first. All positive finite bandwidth/damping inputs must work, including binary64 extremes. With dt=0 no mapping/rate/reference update occurs. -
For every accepted inlier (including dt=0), increment the lock run up to lock_count if abs(e)<=lock_threshold_ns; otherwise clear it. Equality counts.
-
Jitter: first accepted inlier after anchor/step/reset initializes m=e*e; later accepted inliers update
m += (e*e-m)/16. Set last accepted to sample local and return accepted. Anchor/step are not jitter samples. Jitter is 0 until two inliers have been accepted, then round_away(sqrt(m)) ns, saturated to the signed-time range. Use the unrounded e, not observation.error_ns.
For accepted/rejected/stepped results, observation.error_ns is round_away(e) saturated to [Imin,Imax]. Anchored/pending errors are zero. There is no exception merely because a finite phase error exceeds the signed duration range.
Queries, rounding, holdover and reset
round_away means nearest integer with half ties away from zero, not Python's
built-in round, which uses ties to even. Mapping rounds displacement, not
absolute time:
- local(r) = I0 + round_away(frac + (r-R0)*Pn/(1+y)).
- remote(l) = R0 + round_away(((l-I0)-frac)*(1+y)/Pn).
- Both raise NotAnchoredError before anchoring and PllOverflowError if the final integer result does not fit signed 64-bit. Add rounded whole displacement to the integer base exactly, preserving base low bits. A displacement outside signed 64-bit is allowed if cancellation yields a fitting result; the Go wide-displacement behavior must be retained. Do not reject solely because the displacement itself exceeds Imax.
- offset returns y. trim returns round_away(y*10**12), clamped to ±999_999_999_999. Thus every follower trim is in pacer input range, even near max_offset_ppm's limit. Applying it can still fail if a pacer's new anchor overflows; this is not an atomic two-controller transaction.
- state(now) is holdover iff anchored and now-last_accepted>holdover_after_ns, comparing elapsed exactly without signed overflow. Equality is not holdover; earlier now is allowed and does not mutate history. Otherwise return locked if lock run reached lock_count, acquiring if not (also before anchoring). Pending/rejected readings do not refresh last accepted. Holdover does not alter the mapping; extrapolation continues with the last rate estimate.
- reset clears mapping, y, order, pending window, outlier run, lock and jitter; retains configuration. Earlier readings may anchor afresh.
Binary64 follower estimates are not exact rational time and arbitrarily distant
extrapolation is not nanosecond-accurate. Round trips can lose ticks/ns; no exact
inverse or cross-platform bit-identical float guarantee is made. Boundary
rounding, saturation and integer anchors are nevertheless contractual. For
example a 0.5 ns period with anchor (local=1,remote=0) maps remote -1 to
1+round_away(-0.5)=0; anchor (-1,0) maps remote 1 to 0.
Cross-module success and failure
from dataclasses import replace
from pll import (Follower, Pacer, Status, State, default_follower_config,
units_per_second, OrderError, InvalidArgumentError,
NotAnchoredError, ConfigError)
rate = units_per_second(1000, 1)
f = Follower(replace(default_follower_config(rate), bandwidth_hz=1.0, damping=1.0))
try:
f.local(0)
except NotAnchoredError:
pass
else:
raise AssertionError("unanchored query must fail")
assert f.observe(0, 0).status == Status.ANCHORED
obs = f.observe(1_001_000_000, 1000) # 1 ms late; dt=1.001 s, x=0.5, kp=1
assert (obs.status, obs.error_ns) == (Status.ACCEPTED, 1_000_000)
assert f.local(1000) == 1_001_000_000
assert f.trim() == -249_750_250 # y = -0.25 / 1.001 * 0.001
p = Pacer(rate)
p.claim(1000)
p.set_trim(f.trim())
assert list(p.claim(2).all()) == [(1000, 1_000_000_000), (1001, 1_001_000_249)]
before = (f.offset(), f.local(1000), p.next_due(), p.trim())
try:
f.observe(1_001_000_000, 1000) # remote did not increase
except OrderError:
pass
else:
raise AssertionError("order must fail")
try:
p.set_trim(1_000_000_000_000)
except InvalidArgumentError:
pass
else:
raise AssertionError("trim must fail")
assert before == (f.offset(), f.local(1000), p.next_due(), p.trim())
try:
Follower(replace(default_follower_config(rate), bandwidth_hz=0.0, lock_count=0))
except ConfigError as exc:
assert (exc.field, exc.reason) == ("bandwidth_hz", "must be finite and > 0")
else:
raise AssertionError("config must fail on its first invalid field")
Additional deterministic workflows, each starting with a fresh follower:
| Inputs/settings | Promised outcome |
|---|---|
| Default 1000 ticks/s; observe(0,0), then (k10_000_000,k10) for k=1..8 | Anchored, then eight accepted errors 0; offset/trim/jitter 0; locked at 80 ms. At now=5_080_000_000 still locked, at 5_080_000_001 holdover. |
| Same rate/defaults; anchor(0,0), then (10_000_000,2010), (20_000_000,2020), (30_000_000,2030) | Errors -2_000_000_000: rejected, rejected, stepped; y stays 0; local(2030)=30_000_000; acquiring, jitter 0. |
| Rate 10**9, window_ns=4; (0,0),(1,1),(4,4),(5,5) | Anchored, pending, pending, accepted. Equal errors keep candidate (1,1); (5,5) starts next window. Last accepted=1, not 5. |
| Rate 10**9; anchor(Imax,0); local(1) | PllOverflowError, state unchanged. |
Ownership, effects and concurrency
Pacer and Follower each need one owner; aliases refer to the same mutable controller. No thread safety, GIL-based transaction guarantee or async-task synchronization is promised. Serialize calls externally or protect controllers with a caller-owned lock. Copying/pickling controllers and persistence formats are unsupported. Rate, Span, FollowerConfig and Observation are immutable values; share them read-only, and old spans remain valid while a pacer changes. No mutable caller configuration is retained. Results do not retain payload data.
The library does no I/O, network access, timers, sleeping, subprocess/process creation, threads, implicit clock reads, environment reads or credential access. It keeps only in-memory timing/config/history and touches no payloads. The caller supplies monotonic elapsed ns, origin alignment, counter unwrapping, clock acquisition, wakeups, cancellation, backpressure and transport adapters. The pacer accepts an earlier now without rewinding; the follower rejects backwards input, so choose clocks/adapters accordingly.
Build/install/test tools are different: Python may write __pycache__, pip can
write environment/build/cache files, tests consume CPU and may write controlled
fixture/cache outputs. None of these are promised library runtime effects.
No network or credentials are required by the deterministic checks.
Verification
Run the deterministic standard-library tests from the repository root:
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/check_tree.py
Tests cover exact pacing against an independent rational oracle, follower models and boundary cases, failure preservation, README examples and replay of pinned public-Go fixtures. Finite fixtures are not proof of universal parity or portable performance. See delivery evidence for historical checks and their numerical limits.
To build a local distribution, use an existing build environment containing scripts/build-requirements.txt, then run:
python -I -m build --no-isolation --sdist --wheel --outdir "$DIST_DIR"
Build from a separate source copy and choose an external output directory to keep build artifacts outside the checkout. Build dependencies are not runtime dependencies. No registry release is claimed.
Metadata
Release files for phase-locked-loop 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| phase_locked_loop-0.1.0.tar.gz | 49.0 kB | Without provenance | Details for phase_locked_loop-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phase_locked_loop-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for phase_locked_loop-0.1.0-py3-none-any.whl |
Total release size: 77.6 kB
Release files / phase_locked_loop-0.1.0.tar.gz
| Download URL | phase_locked_loop-0.1.0.tar.gz |
|---|---|
| Size | 49.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9c983f95ee559392c11cd0bffc020b793befc93a58d6bd57d17bb5e6cda8e882
|
|
BLAKE2b-256 checksum How to use checksums |
70323b490ca5ee81077a6f21fde79e4772921f43ae29a84d6b29c4981d8d5404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Release files / phase_locked_loop-0.1.0-py3-none-any.whl
| Download URL | phase_locked_loop-0.1.0-py3-none-any.whl |
|---|---|
| Size | 28.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6663d85e529831a415d50eae490e303f7cfca6c37c6e305b9160a053072bde3d
|
|
BLAKE2b-256 checksum How to use checksums |
56348b8b922a80ca98d0e34d8eef1f292a54d29fa35e7a83317be48bb3497ecd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Security for phase-locked-loop 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.