Frequency Logic & Threshold Tuning

Telecom infrastructure operations require deterministic scheduling, not reactive guesswork. Frequency logic and threshold tuning form the computational core that decides how often each antenna structure is inspected — the engine that turns continuous telemetry and contractual deadlines into a single, defensible inspection interval per tower. This page is the timing layer of the broader Intelligent Inspection Scheduling & Technician Routing architecture: the components documented elsewhere decide when a viable window opens and who is dispatched, while the logic described here decides how urgently each site needs attention in the first place. When municipal zoning codes, carrier SLAs, and structural load limits intersect, static calendar-based inspections become simultaneously wasteful and legally exposed, and only a continuously tuned frequency function keeps both problems in check.

The Core Challenge #

The failure mode this engine exists to prevent is familiar to every portfolio manager who has run inspections off a spreadsheet. A fixed annual cadence treats a fifteen-year-old guyed tower in a high-wind coastal county exactly like a three-year-old monopole in a sheltered inland lot. The result is a two-sided loss: the old, exposed structure is under-inspected until a corroded anchor or a fatigued bolt becomes an incident, while the young, quiet structure is over-inspected, burning climb crews, permits, and lease-holder goodwill on visits that find nothing. Neither error is visible on the calendar — both look like “compliant” until the day one of them isn’t.

Naively reacting to raw telemetry is a different failure with the same root cause. A single vibration spike from a passing storm front, or a transient sensor glitch on a cold morning, should not compress a tower’s inspection interval from 180 days to 45 and scramble a crew. If every reading moves the schedule, dispatch oscillates: work orders are created, superseded, and cancelled faster than crews can service them, and the audit trail becomes an unreadable churn of reversed decisions. The engineering requirement is therefore twofold — the interval must respond to sustained physical degradation and to hard contractual deadlines, but it must be damped against noise so that only a genuine, persistent change in a tower’s risk profile ever moves its cadence.

Data Model & Schema #

Every decision the engine makes operates on one strongly typed record: the ComplianceVector. It carries everything the frequency function needs to know about a single structure — its age, its structural class, its recent fault history, its contractual floor, and its live telemetry — so that tuning is a pure function of the vector and never reaches out to hidden global state. Keeping the vector explicit is what makes each decision reproducible and auditable: given the same vector, the engine must always return the same interval.

Represented as a dataclass, the vector stays a flat, serialisable unit of work that travels with the tower through every scheduling cycle:

from dataclasses import dataclass

@dataclass
class ComplianceVector:
    site_id: str                 # e.g. "TWR-4417"
    structural_age_years: float
    structural_class: str        # monopole | guyed | self_support
    fault_density: float         # faults per year
    lease_mandate_days: int      # contractual maximum interval
    vibration_sigma: float       # live telemetry, sigma from baseline
    base_interval_days: int = 180
    last_interval_days: int = 0  # 0 = never inspected

Algorithmic or Architectural Approach #

The tuning function composes three independent multipliers over the class base interval, then clamps the result against both a contractual floor and hard safety bounds. A degradation factor scales with structural age and historical fault density, tightening the interval for assets that are physically more likely to develop defects. A telemetry factor scales with live vibration sigma, compressing the interval when sensors report sustained motion beyond baseline and relaxing it when a structure is measurably quiet. The base interval divided by the product of these factors yields a raw, physics-driven interval before any contract or damping is applied.

Two guards then shape that raw value. First, the lease_mandate_days acts as a hard ceiling: no matter how quiet a tower is, the engine will never schedule beyond the interval the carrier lease or municipal ordinance mandates, so a compliant-looking sensor reading can never push a site out of contractual bounds. Second — and this is what separates a production engine from a naive rule — the result passes through a hysteresis band before it is committed. The engine only moves a tower’s cadence if the newly computed interval differs from the last committed interval by more than a set percentage, or if vibration sigma has shifted beyond a set delta. Minor fluctuations inside the band are absorbed: the previous interval holds, dispatch stays stable, and the audit log records a deliberate “hold” rather than a churn of reversals.

Figure: adaptive frequency calculation with hysteresis damping.

The hysteresis band is the hardest idea on this page to picture, because its whole point is that most telemetry movement produces no schedule change at all — the interval only steps when a reading crosses the band edge and stays there.

Validation & Compliance Gates #

A computed interval is not a trusted interval until it clears two gates. The first is contractual validation. Before the tuned value is committed, the engine re-checks it against lease_mandate_days and against the absolute safety bounds of 30 to 365 days. A vector whose lease mandate is missing, non-positive, or shorter than the safety floor is not silently coerced — it is rejected into a quarantine path so a lease manager reconciles the contract rather than letting the scheduler invent a deadline. This mirrors the canonical-record discipline used downstream by the Zoning Rule Engine Design, where a malformed input is a compliance event, not a rounding problem.

The second gate is decision sealing. Every committed interval is serialised into a canonical record — site, inputs, computed factors, and final interval — and hashed with hashlib.sha256. That digest is written into both the returned decision and the structured audit log. During a regulatory inspection an operator can then prove that the interval scheduled for a given tower on a given day was the exact output of a specific vector, not a manual override entered after the fact. When a threshold breach is severe enough that the engine drops to the minimum interval, the same sealed record is what escalates to regional engineering leads, so an emergency compression is auditable end to end rather than an unexplained calendar change.

Integration Points #

Frequency logic sits at the head of the scheduling chain, so its value is entirely in what consumes its output. The tuned interval is the input to Weather Window Optimization, which cross-references forecasted wind shear, precipitation, and lightning risk against each tower’s urgency to find a safe climb window — a tightly compressed interval raises a site’s priority when several towers compete for the same clear-weather day. Once a window is fixed, the work order flows into Technician Assignment Algorithms, which match certification, proximity, and equipment against the scheduled visit before dispatch. The frequency engine stays deliberately unaware of weather and crews; it owns urgency, and the sibling components own feasibility and assignment.

The concrete mechanics of the degradation multiplier — exactly how age and load curves translate into a factor — are worked through in the task walk-through Dynamic Inspection Frequency Calculation Based on Tower Age and Load, which takes a single ComplianceVector and shows the interval falling out step by step. For a downstream view of what happens after urgency is set, the routing example in Optimizing technician routes for multi-site maintenance windows shows how several tuned intervals across a region are sequenced into a single day’s route.

Python Implementation #

The module below is a complete, runnable tuning engine. It computes the degradation and telemetry factors, enforces the lease-mandate floor and safety clamp, damps the result through a hysteresis band, isolates bad input behind a custom exception, and seals every committed decision with a SHA-256 audit hash. All identifiers use realistic telecom site codes, and every terminal state emits a structured, compliance-grade log line.

import hashlib
import json
import logging
from dataclasses import dataclass, asdict
from typing import Optional, Tuple

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
    handlers=[logging.FileHandler("threshold_audit.log"), logging.StreamHandler()],
)
logger = logging.getLogger("telecom.threshold_tuning")


class ThresholdTuningError(Exception):
    """Raised when a compliance vector cannot yield a valid interval."""


@dataclass
class ComplianceVector:
    site_id: str
    structural_age_years: float
    structural_class: str
    fault_density: float
    lease_mandate_days: int
    vibration_sigma: float
    base_interval_days: int = 180
    last_interval_days: int = 0


class ThresholdTuningEngine:
    """Adaptive inspection cadence with lease floors and hysteresis damping."""

    MIN_INTERVAL, MAX_INTERVAL = 30, 365
    HYSTERESIS_PCT, HYSTERESIS_SIGMA = 0.15, 0.2

    def tune(self, v: ComplianceVector) -> dict:
        if v.lease_mandate_days < self.MIN_INTERVAL:
            raise ThresholdTuningError(
                f"{v.site_id}: lease mandate {v.lease_mandate_days}d below safety floor"
            )

        # Older assets and higher fault history tighten the interval.
        degradation = 1.0 + (v.structural_age_years * 0.025) + (v.fault_density * 0.10)
        # Sustained vibration above baseline compresses; quiet structures relax.
        telemetry = max(0.8, 1.0 + (v.vibration_sigma - 0.5) * 0.4)

        raw = int(v.base_interval_days / (degradation * telemetry))
        floored = min(raw, v.lease_mandate_days)          # contractual ceiling
        clamped = max(self.MIN_INTERVAL, min(self.MAX_INTERVAL, floored))

        committed, held = self._apply_hysteresis(clamped, v)
        decision = {
            "site_id": v.site_id,
            "degradation_factor": round(degradation, 4),
            "telemetry_factor": round(telemetry, 4),
            "raw_interval_days": raw,
            "committed_interval_days": committed,
            "held": held,
        }
        decision["audit_hash"] = self._seal(decision)
        logger.info(
            "AUDIT | %s | %s | interval=%dd | %s",
            v.site_id, "HELD" if held else "COMMIT",
            committed, decision["audit_hash"][:12],
        )
        return decision

    def _apply_hysteresis(self, candidate: int, v: ComplianceVector) -> Tuple[int, bool]:
        if v.last_interval_days == 0:
            return candidate, False  # first ever schedule: always commit
        delta_pct = abs(candidate - v.last_interval_days) / v.last_interval_days
        if delta_pct < self.HYSTERESIS_PCT and abs(v.vibration_sigma) < self.HYSTERESIS_SIGMA:
            return v.last_interval_days, True  # inside band: hold previous
        return candidate, False

    @staticmethod
    def _seal(decision: dict) -> str:
        canonical = json.dumps(decision, sort_keys=True, separators=(",", ":"))
        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()


if __name__ == "__main__":
    engine = ThresholdTuningEngine()
    vector = ComplianceVector(
        site_id="TWR-4417", structural_age_years=14.0, structural_class="guyed",
        fault_density=1.2, lease_mandate_days=120, vibration_sigma=0.9,
        base_interval_days=180, last_interval_days=150,
    )
    print(json.dumps(engine.tune(vector), indent=2))

Testing & Verification #

Scheduling bugs are invisible until a season of readings replays them, so the engine is verified with fast, deterministic assertions rather than live telemetry. Three properties matter most: the lease mandate is honoured as a hard ceiling, the hysteresis band genuinely absorbs small changes, and the audit hash is stable for identical inputs. The stubs below use pytest:

import pytest

def _vector(**kw):
    base = dict(site_id="TWR-8842", structural_age_years=5.0, structural_class="monopole",
                fault_density=0.0, lease_mandate_days=200, vibration_sigma=0.5,
                base_interval_days=180, last_interval_days=0)
    base.update(kw)
    return ComplianceVector(**base)

def test_lease_mandate_is_a_hard_ceiling():
    # A quiet young tower would compute a long interval, but the lease caps it.
    out = ThresholdTuningEngine().tune(_vector(lease_mandate_days=90, vibration_sigma=0.1))
    assert out["committed_interval_days"] <= 90

def test_small_change_is_held_by_hysteresis():
    out = ThresholdTuningEngine().tune(_vector(last_interval_days=178, vibration_sigma=0.5))
    assert out["held"] is True
    assert out["committed_interval_days"] == 178

def test_short_lease_is_rejected():
    with pytest.raises(ThresholdTuningError):
        ThresholdTuningEngine().tune(_vector(lease_mandate_days=10))

def test_seal_is_deterministic():
    d = {"site_id": "TWR-8842", "committed_interval_days": 120}
    assert ThresholdTuningEngine._seal(d) == ThresholdTuningEngine._seal(d)
    assert len(ThresholdTuningEngine._seal(d)) == 64

A healthy run of the __main__ demo commits a compressed interval for the aged, actively vibrating TWR-4417 and prints a sealed decision:

2026-07-03 09:14:02 | INFO | telecom.threshold_tuning | AUDIT | TWR-4417 | COMMIT | interval=104d | 7c1e9a3f2b40
{
  "site_id": "TWR-4417",
  "degradation_factor": 1.47,
  "telemetry_factor": 1.16,
  "raw_interval_days": 105,
  "committed_interval_days": 104,
  "held": false,
  "audit_hash": "7c1e9a3f2b40..."
}

A failure shows one of two signatures: a held: true on a vector whose sigma clearly exceeds the band means the hysteresis delta is mis-signed and dispatch will freeze; a committed interval above lease_mandate_days means the contractual floor was applied after the clamp instead of before it. Both are caught by the assertions above before code reaches production.

Operational Considerations #

Tuning the multiplier constants is the most consequential operational decision, and it is portfolio-specific. The 0.025 age coefficient and 0.10 fault coefficient that suit a coastal, high-corrosion region will over-tighten a dry inland portfolio and waste climb capacity; operators should fit these against their own incident history rather than inherit defaults. The hysteresis width trades stability against responsiveness: a wider band produces a calmer dispatch schedule but a slower reaction to genuine degradation, so safety-critical structural classes typically run a narrower band than routine RF-only sites.

Three telecom-specific edge cases recur. Field sensors drop offline, delivering a stale or null vibration_sigma; the engine must treat a missing signal as elevated risk and fall back to the class base interval rather than assuming the tower is quiet, so absence of data never relaxes a schedule. Multi-jurisdiction portfolios carry different lease mandates per site, so the contractual floor is always read from the vector, never from a global constant — a threshold safe for one county’s ordinance will violate another’s. Never-inspected towers arrive with last_interval_days = 0 and must bypass hysteresis entirely, because there is no previous interval to damp against; committing the first schedule immediately is correct, and only subsequent cycles enter the band. Finally, keep the audit log append-only and rotate by size, never by deletion, since the retention window regulators expect for antenna-structure records outlives most log-rotation defaults.

FAQ #

Related #

• Up to the parent architecture: Intelligent Inspection Scheduling & Technician Routing
• Sibling component: Weather Window Optimization
• Sibling component: Technician Assignment Algorithms
• Task walk-through: Dynamic Inspection Frequency Calculation Based on Tower Age and Load
• Downstream routing: Optimizing technician routes for multi-site maintenance windows