Formatos de registro de relógio
src/clock_log.rs lê um registro medido de relógio em uma única série de fase normalizada: uma grade uniforme de amostras (time_s, phase_s), com o intervalo de amostragem tau0 declarado ou encontrado, cada lacuna contada e as unidades do registro nomeadas. Oito formatos são lidos, cada um um subconjunto documentado. Tudo o que estiver fora do subconjunto é recusado com um erro que nomeia o que foi encontrado, em vez de ser lido de forma aproximada.
Abreviações. RINEX é o Receiver Independent Exchange Format. TICC é o contador de intervalos de tempo da TAPR (Tucson Amateur Packet Radio). ADEV é o desvio de Allan sobreposto, TDEV o desvio de tempo e MTIE o erro máximo de intervalo de tempo. tau0 é o intervalo de amostragem em segundos.
Onde um registro pode ser usado#
telecom-timing:[series.clock_log]no lugar deseries.samplesouseries.csv_path. A fase do registro, em ns, é a série de erro de tempo verificada contra as máscaras, e o relatório ganha um blococlock_logque diz como foi lida.- O tipo de cenário de relógio: uma tabela
[clock_log]acrescenta um blocomeasuredà execução: como o registro foi lido, o SHA-256 da tabela (input_sha256; oscenario_hashda execução não cobre a tabela) e das amostras de fase, e o ADEV sobreposto, o TDEV e o MTIE em fatores de média oitavados. Exigeruns = 1. O holdover simulado permanece inalterado.
Sem a tabela, ambos os tipos de cenário são analisados, geram hash e informam exatamente como antes.
[clock_log] # or [series.clock_log] in a telecom-timing scenario
format = "ticc" # "rinex-clk", "timelab", "ticc", "ptp4l", "phc2sys", "ts2phc",
# "chrony-tracking" or "chrony-statistics"
path = "logs/ticc.txt" # or text = "..." inline (the only choice in WebAssembly)
channel = "chA" # TICC: needed when the log holds more than one channel
gaps = "linear" # "refuse" (default), "longest" or "linear"
# clock = "G08" # RINEX, linuxptp, chrony: needed when the log holds more than one clock or source
# tau0_s = 1.0 # overrides a header and the detected spacing
# units = "ns" # TimeLab phase units: s (default), ms, us, ns, ps
# data = "phase" # TimeLab: phase (default) or frequency
Os formatos#
rinex-clk: arquivos de relógio RINEX, versões 2,00 e 3,00 a 3,04 (incluindo o campo de nome de nove caracteres da 3,04). O registro RINEX VERSION / TYPE é verificado e qualquer outra versão é recusada, nomeando a versão encontrada: o IGS publica o formato de relógio (rinex_clock300.txt, 302, 304) até a 3,04, e os documentos RINEX 4,00, 4,01 e 4,02 definem apenas arquivos de observação, de navegação e meteorológicos, portanto não existe versão 4,00 do arquivo de relógio a ser lida. O cabeçalho é lido apenas para o seu TIME SYSTEM ID e é ignorado até END OF HEADER. Dos registros de dados, apenas os registros AS (satélite) e AR (receptor ou estação) de um relógio, selecionado pelo nome, são mantidos. Seu primeiro campo de valor, o viés do relógio em segundos, é a fase. As linhas de continuação e os registros CR, DR e MS são ignorados. As épocas são os campos de calendário do registro, em segundos a partir de 1980-01-06 00:00:00 no sistema de tempo do próprio arquivo, sem conversão.
timelab: registros ASCII de fase ou de frequência no estilo TimeLab, a forma em texto simples que o TimeLab exporta e que a importação ASCII dele e o Stable32 leem. Há uma leitura por linha: ou uma única coluna com tau0 uniforme, ou duas colunas time value. As colunas podem ser separadas por espaço em branco, vírgulas ou ponto e vírgula.
- Linhas iniciadas por
#,;ou%são comentários. Um comentário da formakey = value(oukey: value) definetau0(s),units(s,ms,us,nsoups, para fase),data(phaseoufrequency) outime_units(soumjd, para a primeira de duas colunas). - Uma linha inicial não numérica é tomada como cabeçalho de coluna.
- Dados de frequência (frequência fracionária) são aceitos somente em uma coluna. São integrados em fase como
x[i+1] = x[i] + y[i]·tau0(NIST SP 1065, 2008, §4,1). - Os arquivos de projeto binários e
.timdo TimeLab não são lidos.
ticc: registros do contador TICC da TAPR (Manual de Operação do TICC, revisões de 23 de novembro de 2016 e 15 de dezembro de 2025, "modos de medição"). Todo campo de dados é em segundos com 12 casas decimais (11 por padrão a partir do firmware 20251101: qualquer quantidade até 15 é lida). Um carimbo de tempo é lido a partir do seu texto decimal como um número inteiro de femtossegundos, e não como um número binário de ponto flutuante, de modo que a fase de um registro obtido dias após o início do contador mantém a resolução própria do contador: um carimbo de tempo f64 em 3.0e5 s tem um espaçamento de 5.8e-11 s, cerca dos 60 ps do contador.
- As linhas do modo de carimbo de tempo (
<seconds> chA,<seconds> chB) e o canal de pseudocarimbo de tempo do modo TimeLab (chC) são carimbos de tempo de eventos. A fase do canal selecionado é o seu carimbo de tempo menos o tique nominal:x[k] = t[k] − t[0] − n[k]·tau0, em quen[k]é o número inteiro detau0desde o primeiro evento. Um evento perdido é uma lacuna. - As linhas do modo de intervalo (
<seconds> TI(A->B), ou qualquer rótulo iniciado porTI) são lidas diretamente como fase, uma leitura portau0. O cenário deve declarartau0_s, porque a linha não traz tempo. - O modo Paired Timestamp imprime as mesmas linhas na ordem dos canais e é lido como modo Timestamp; o modo 3-Corner Hat acrescenta o
chCsintetizado, lido como acima. - A saída dos modos Period e Debug é recusada. Um canal cujas leituras não crescem é informado como modo Period. O modo Binary Timestamp não é texto, e um arquivo nesse modo é recusado com uma mensagem que o diz.
- Linhas iniciadas por
#, e linhas que não são<number> <label>(como o menu de inicialização), são ignoradas e contadas.
Registros do linuxptp e do chrony#
Estes cinco formatos leem o que um daemon de tempo em execução escreve sobre o próprio relógio. Servem para verificar uma cadeia de temporização depois do fato (um boundary clock, o PHC de um grandmaster, um cliente chrony) com os mesmos estimadores dos demais registros. Não leem a configuração de um daemon, e nada aqui se comunica com um daemon.
ptp4l, phc2sys, ts2phc: as linhas de servo do linuxptp, cada formato lendo apenas as linhas do seu próprio programa. Uma leitura é uma linha da forma
ptp4l[5003.000]: master offset 40 s2 freq +1480 path delay 497
phc2sys[7000.000]: CLOCK_REALTIME phc offset -30 s2 freq +100 delay 1200
ts2phc[8000.000]: /dev/ptp0 offset 3 s2 freq -2
- O carimbo de tempo é o primeiro
[seconds.fraction]da linha (o relógio monotônico do daemon). Ele também é lido depois de um prefixo de syslog, em que um identificador de processo comoptp4l[812]:não tem fração e não é tomado. - A fase é o
offsetregistrado, em nanossegundos, convertido em segundos. É o erro de tempo medido pelo daemon do seu relógio escravo contra a sua referência, como registrado: positivo quando o escravo está adiantado. É o erro que resta sob controle do servo, e não a deriva de um relógio em funcionamento livre. - As palavras entre o carimbo de tempo e
offsetnomeiam a fonte (master,eth0 masterpara um prefixo[eth0],CLOCK_REALTIME phc,/dev/ptp0). Um registro com mais de uma fonte precisa declock = "<that text>"; o erro as lista. - As leituras anteriores ao primeiro momento em que o servo informa
s2(travado) ficam de fora e são contadas emn_skipped_lines:s0es1são os estados destravado e de salto, cujos desvios são transitórios de acomodação. Um servo que nunca alcanças2é recusado. Uma linha sem campo de estado é lida como está. - As linhas de resumo (
rms ... max ...), as mensagensdelayeselected best mastere as linhas de outros programas são ignoradas e contadas. - Carimbos de tempo que retrocedem (um daemon reiniciado) são recusados; divida o registro.
chrony-tracking, chrony-statistics: os arquivos log tracking e log statistics do chrony, lidos por posição de coluna. Uma leitura é uma linha com pelo menos 14 colunas (tracking) ou 13 (statistics) que começa com uma data e hora UTC YYYY-MM-DD HH:MM:SS. A linha de cabeçalho de colunas é ignorada e contada; a linha ==== abaixo dela é ignorada sem ser contada.
- Tracking: coluna 7, o desvio local na atualização do relógio, em segundos. O endereço IP ou o identificador de referência muda com a fonte selecionada, de modo que, sem
clock, toda linha é lida como um único relógio local.clock = "<id>"mantém um identificador de referência. - Statistics: coluna 5, o desvio estimado de uma fonte, em segundos. Há uma série por endereço de fonte, e o registro precisa de
clock = "<address>"quando contém mais de uma. - As épocas são segundos a partir de 1980-01-06 00:00:00 UTC, sem tratamento de segundos intercalares. O chrony escreve uma linha por atualização ou por amostra de fonte, de modo que o espaçamento não é uniforme.
tau0é o espaçamento mediano; uma leitura a menos de meiotau0da anterior mantida é descartada e contada emn_duplicates, e um espaçamento maior é uma lacuna, quegaps = "refuse"informa. Informetau0_segaps = "linear"para um registro com intervalo de consulta constante.
As colunas do chrony e os formatos de linha do linuxptp são os da documentação pública dos daemons. As fixtures em tests/fixtures/clock_log/linuxptp_chrony/ foram escritas para o Kshana com valores inventados (veja o NOTICE.md); nenhum registro real foi lido, de modo que um formato que difira entre versões do daemon ainda pode ser recusado ou mal lido. Uma linha que não corresponde é ignorada e contada, nunca adivinhada.
tau0 e lacunas#
Quando o registro traz carimbos de tempo e nenhum tau0 é informado, tau0 é o espaçamento mediano de carimbos de tempo consecutivos, arredondado para quatro algarismos significativos, e a fonte é informada como median-spacing. O espaçamento de um contador difere do nominal pelo desvio de frequência da referência, partes em 10^6 ou menos. Um tau0_s no cenário sempre prevalece (fonte input), seguido de um comentário de cabeçalho tau0 (fonte header).
As amostras são colocadas na grade t0 + i·tau0, e uma época ausente é uma lacuna. Leituras a mais de 1 % de tau0 fora da grade são descartadas e contadas, assim como as duplicatas (a primeira é mantida). A política de lacunas é uma destas:
refuse(o padrão): qualquer lacuna é um erro que conta as lacunas;longest: manter o trecho mais longo sem lacunas;linear: preencher as lacunas internas por interpolação linear e informar o número de preenchidas.
Os estimadores precisam de um registro sem lacunas, e é por isso que as lacunas são resolvidas aqui.
Seu próprio relógio#
Uma tabela [clock_log] no tipo de cenário de relógio informa quão estável foi o seu próprio relógio, ao lado da simulação: scenarios/clock-measured-log.toml (kshana example clock-measured-log) é clock-holdover.toml com um trecho de 96 leituras de um relógio de satélite do IGS como um registro TimeLab embutido. Substitua text por path e format para o seu próprio arquivo. O bloco measured no resultado contém como o registro foi lido (formato, tau0 e a origem, cada lacuna) e suas ADEV, TDEV e MTIE; ele não altera a simulação.
Conduzir o holdover com o seu próprio relógio: [clock_fit]#
[clock_log] # the measured series, as above
format = "ticc"
path = "my-clock.txt"
channel = "chA"
[clock_fit]
replaces = "classical" # or "quantum": the simulated clock whose noise the log replaces
O registro é ajustado com o procedimento de cartão de dispositivo de src/clock_library/card.rs (condicionamento, remoção do termo quadrático, identificação do ruído de defasagem 1, mínimos quadrados ponderados em PM branco, FM branco, FM de cintilação e FM de passeio aleatório nos tempos de média com pelo menos 30 graus de liberdade). O relógio nomeado passa então a usar q_wf = h_0 / 2, q_rw = 2 pi^2 h_-2, flicker_floor = sqrt(2 ln 2 h_-1) e o drift ajustado; y0 permanece como está no cenário, porque um registro traz o deslocamento da sua referência, e não o do relógio após a disciplina. O ruído de fase branco é ajustado e informado, mas não simulado. O resultado ganha um bloco fitted (os coeficientes, os pontos de ajuste, os valores usados pela execução, o que foi deixado de fora, o SHA-256 do registro) e o relógio recebe o id measured:<12 hex of the phase hash>. Com runs > 1 o conjunto sorteia a partir do relógio ajustado (o bloco measured exige runs = 1). Um ajuste sem ruído de frequência, um registro curto demais para ajustar e um replaces diferente de quantum ou classical são erros que o dizem. scenarios/clock-fitted-log.toml é um exemplo (6 horas de um relógio de satélite do IGS).
O que a comparação com ruído conhecido (tests/fixtures/clock_fit/RESULTS.md) mostra e o que se deve ter em mente:
- Atingido: o nível de FM branco é recuperado dentro de 5 % em todo registro sintético que o tem; o cartão ajustado reproduz o desvio de Allan verdadeiro dentro de um fator de 1,35 em todo tempo de média em que foi ajustado; o expoente de ruído que o ajuste identifica é igual ao do allantools em todos os pontos (no registro 5071A, depois que o salto de fase que o condicionamento remove é removido também da entrada do allantools).
- Não atingido, e fixado pelo teste: o FM de passeio aleatório só é recuperado quando domina os maiores tempos de média do registro e, mesmo assim, em um de três registros de uma série de 131.072 s com cruzamento em 3.000 s, o ajuste o atribuiu ao FM de cintilação e à deriva. A divisão entre FM de passeio aleatório e FM de cintilação não é confiável a partir de um único registro. A execução reproduz a estabilidade do registro nos tempos de média que o registro cobre; além deles as duas escolhas divergem (o FM de cintilação é um piso constante, o FM de passeio aleatório cresce com a raiz quadrada do tempo de média).
- MODELLED: um cenário hipotético para o ruído desse relógio como o registro o mostra, não uma calibração do relógio e não uma previsão do seu comportamento futuro.
Um registro malformado é um erro que nomeia o que foi encontrado (a linha, a versão, o seletor ausente), nunca um resultado parcial: tests/clock_log_real_allantools.rs fixa 24 desses casos.
Evidências#
MODELLED. Este é um analisador, e sua saída alimenta estimadores que são validados em outro lugar em relação ao allantools. Os testes unitários de src/clock_log.rs usam pequenos registros escritos à mão e, para os formatos linuxptp e chrony, os arquivos de teste de tests/fixtures/clock_log/linuxptp_chrony/. tests/clock_log_allantools.rs executa a comparação fixada antecipadamente em tests/fixtures/clock_log/PREREGISTRATION.md: três registros sintéticos com semente, um por formato, relidos por um leitor independente escrito a partir desta página pelo mesmo autor, com as ADEV, TDEV e MTIE verificadas em relação ao allantools 2024,6; essa comparação cobre apenas os três primeiros formatos, e os leitores de linuxptp e chrony têm testes de analisador, mas nenhuma comparação com referência independente. Os registros dessa comparação são sintéticos, portanto nada ali descreve um relógio ou contador real; a comparação com séries medidas é descrita abaixo.
Com dados medidos#
tests/clock_log_real_allantools.rs executa a comparação fixada antecipadamente em tests/fixtures/clock_log_real/PREREGISTRATION.md (versionada antes de qualquer arquivo de teste ou execução) em quatro séries medidas: o PHASE.DAT do Stable32, as primeiras 65.536 leituras de um relógio de césio 5071A contra um maser de hidrogênio, e os relógios do satélite G01 do IGS (30 s) e da estação ABMF (300 s) a partir do relógio final do IGS de 2026-08-02, como um recorte incorporado com seu NOTICE. Os dois primeiros não têm concessão de redistribuição: os registros escritos a partir deles estão em realdata-cache/, ignorado pelo git (scripts/gen_clock_log_real_ref.py), e o teste o diz e passa quando estão ausentes, a menos que KSHANA_REQUIRE_REALDATA=1. Cada registro é lido pelo motor e por um leitor independente, e ADEV, TDEV e MTIE são comparados com o allantools 2024,6. Registrado em tests/fixtures/clock_log_real/RESULTS.md: no leitor distribuído, os registros TICC, a versão do cabeçalho e cinco mensagens de erro falharam nos limiares fixados antecipadamente; foram corrigidos e a comparação foi executada de novo sem alterações. Atingido, exceto um par: o MTIE de um registro de frequência difere do do allantools, porque o allantools integra a frequência menos a sua média (fixado como NOT MET; a comparação em condições equivalentes é atingida). A linha permanece MODELLED: os registros TICC são dados de relógio medidos recodificados no formato do contador pelo nosso script (nenhuma captura TICC real foi encontrada), e o leitor de referência tem o mesmo autor que o do motor.