Sinusoidal Time Encoding

Fourier decomposition of time

A standard Fourier decomposition expresses a signal as a sum of sinusoids at different frequencies. The Temporal Spiral applies the same idea to time itself: rather than decomposing a measured signal, it decomposes the timestamp t into twelve independent frequency components, one per scale.

For scale i with cycle length T_i:

θ_i  =  2π × (t mod T_i) / T_i     ∈ [0, 2π)

f_i  =  [ sin(θ_i), cos(θ_i) ]      ∈ ℝ²

Concatenating the twelve f_i vectors gives the full encoding:

φ(t)  =  [ sin(θ_1), cos(θ_1),
            sin(θ_2), cos(θ_2),
            …
            sin(θ_12), cos(θ_12) ]   ∈ ℝ²⁴

This 24-dimensional vector is the Fourier feature map of the timestamp. It is continuous, bounded, and directly differentiable — properties that make it well-suited as an input to attention layers, MLP time encoders, and recurrent controllers.

How this compares to transformer positional encoding

Vaswani et al. (2017) introduced sinusoidal positional encoding for transformers. The Temporal Spiral uses the same mathematical skeleton — but targets calendar time rather than token position.

The key conceptual difference: transformer positional encoding is monotone — it distinguishes token 1 from token 1000 but has no notion of "same time of day". The Temporal Spiral is cyclic per scale, which means two timestamps that share the same hour of day produce the same θ_hr value — a property directly useful for learning daily, weekly, and seasonal patterns.

Why twelve rungs?

Twelve is a deliberate, well-tested general-application anchor — not a mathematical ceiling.

The twelve cycle lengths span twelve orders of magnitude, from one millisecond to one millennium, in approximately one-order-of-magnitude steps:

This coverage gives balanced Fourier bandwidth across every human-relevant time rhythm: sub-second inference cadence, minute/hour scheduling, daily and weekly patterns, seasonal cycles, annual recurrences, and decade-scale trends.

Custom deployments requiring ultra-high precision (sub-microsecond cadence) or deep-time domains (paleoclimatology, orbital mechanics on million-year scales) can request an adjusted rung count. Twelve is the well-tested default that covers the overwhelming majority of AI, robotics, and scheduling applications.

For mathematical background on Fourier feature maps, see Wikipedia: Fourier transform. For the original sinusoidal positional encoding paper, see Vaswani et al. 2017, "Attention Is All You Need".

Ready-to-use feature vector from the API

Every GET /v1/spiral response includes the full 24-dimensional Fourier feature vector in the compact field — ready to concatenate into a model input with no further processing:

curl 'https://api.temporalblock.com/api/v1/spiral' \
  -H 'X-API-Key: tblk_live_…'

// Response (compact field):
{
  "compact": {
    "scales": [
      "us", "ms", "s", "min", "hr",
      "day", "wk", "mo", "yr", "dec", "cen", "mil"
    ],
    "sin": [
      0.000, -0.999,  0.951, -0.309,  0.588,
      0.454, -0.208,  0.866,  0.743, -0.978,  0.991,  0.171
    ],
    "cos": [
      -1.000,  0.009,  0.309,  0.951,  0.809,
       0.891, -0.978,  0.500,  0.669,  0.206,  0.134,  0.985
    ]
  }
}

To build a 24-dimensional input vector in Python:

import numpy as np, requests

r = requests.get(
    "https://api.temporalblock.com/api/v1/spiral",
    headers={"X-API-Key": "tblk_live_…"},
).json()

compact = r["compact"]
# interleave sin/cos: [sin_us, cos_us, sin_ms, cos_ms, …]
fourier_vec = np.array(
    [v for pair in zip(compact["sin"], compact["cos"]) for v in pair]
)  # shape: (24,)

The vector is NTP/NTS-anchored and certified — the timestamp used to compute each θ_i came from an authenticated time source, not the server's unsynchronized system clock.