Indice
Questa è la mappa delle interfacce del framework rilevanti per l'analisi spettrale. La tabella distingue contratti dati, API di infrastruttura, servizi scientifici e presentazione.
1. API e contratti principali
| Interfaccia | Livello | Ruolo |
|---|---|---|
MODULE_API_v1 | Framework | Descriptor e lifecycle dei moduli. |
ANALYSIS_SOURCE_MAP_API_v1 | Framework | Dichiara sorgenti logiche e Dataset selezionati nella Session. |
ANALYSIS_SOURCE_METADATA_RUNTIME_v1 | Runtime | Metadati della sorgente risolta. |
ANALYSIS_SOURCE_ACCESS_RUNTIME_v2 | Runtime | Accesso Dataset-aware dalla sorgente risolta. |
CANONICAL_DATASET_API_v2 | Dati | Lettura backend-neutral tramite Dataset e Variable ID. |
DATASET_VARIABLE_SCHEMA_API_v3 | Dati | Dtype, rank, shape, coordinate e relazioni fra variabili. |
TABLE_STREAM_API_v3 | Dati | Lettura bounded/chunked di Dataset tabellari. |
DATASET_SELECTION_API_v1 | Dati | Selezioni persistenti, per esempio intervalli X/tempo. |
TEMPORAL_SET_API_v1 | Dati temporali | Segmenti e window set riusabili. |
NUMERIC_API_v1 | Servizio scientifico | FFT/IFFT, detrend, finestre, statistiche, algebra e primitive generiche. |
SIGNAL_API_v1 | Servizio scientifico | Matematica di segnale/sistemi e operazioni spettrali riusabili. |
DATASET_PUBLICATION_API_v2 | Output | Pubblicazione transazionale dei Dataset derivati. |
SPECTRUM_TABLE_CONTRACT_v1 | Contratto scientifico | Semantica tabellare comune per spettri derivati. |
UNIT_REGISTRY_API_v1 | Unità | Definizioni e conversioni esplicite di unità. |
PROGRESS_API_v1 | Execution | Avanzamento di analisi lunghe. |
PARALLEL_EXECUTION_API_v1 | Execution | Policy e risorse per calcolo parallelo. |
GRAPH_PROVIDER_API_v1 | Grafica | Lifecycle dei grafici offerti dai moduli. |
PLOT_DATASET_API_v2 | Grafica | Plot persistenti Dataset-native e varianti. |
RENDER_CACHE_API_v1 | Grafica/runtime | Separazione fra stato scientifico e rerender. |
2. Chi possiede che cosa
CORE / framework
Dataset identity, schema, selection, temporal resources, publication,
Session persistence, progress, parallel policy
math.numeric
numerical primitives
math.signal
signal/system primitives
analysis.*
scientific workflow semantics, configuration, outputs, report
plot.dataset / Graph Provider
persistent scientific presentation3. Perché questa separazione è importante
Un modulo non dovrebbe copiare internamente un parser CSV, un sistema di unità, un writer Dataset o un renderer se esiste già un'API pubblica. La separazione rende i workflow riproducibili e consente di cambiare storage o presentazione senza cambiare l'identità scientifica dei dati.
4. API di servizio vs API di modulo
NUMERIC_API_v1 e SIGNAL_API_v1 sono servizi generici. Un modulo Analysis può usarli, ma resta responsabile di definire cosa significa scientificamente il proprio risultato. Per esempio la formula di THD e la ricerca della fondamentale appartengono al workflow Harmonic Analysis, non al semplice fatto che esista una FFT.