50-Parameter Registration Card Template v1.0 | Chapter 3 — Parameter Taxonomy & Naming (Coding Rules)

Home ／ Docs-Technical WhitePaper ／ 50-Parameter Registration Card Template v1.0

Chapter 3 — Parameter Taxonomy & Naming (Coding Rules)

I. Purpose & Scope

• Establish a taxonomy and coding/naming rules for parameters, covering identifiers, aliases & deprecation, cross-pipeline consistency, and traceability.
• For path quantities (arrival time/phase), explicitly show gamma(ell) and the measure d ell in text, and record delta_form ∈ {general, factored} in the card; publication requires p_dim = 1.0.

II. Categories

• PHY | Physical constants: c_ref, λ_ref, k_ref, fundamental constants, etc.
• CAL | Metrology/Calibration: τ_sys, Δτ_ch, gain, PSF, distortion, etc.
• ALG | Algorithm hyperparameters: thresholds, regularization, step sizes, stopping criteria.
• ENV | Environment: α_T, ΔT, humidity/pressure, temperature coefficients.
• GEO | Geometry: q_att, FOV, pixel calibration, distortion grid.
• TIM | Timebase: f_s, t_exp, time windows, heartbeat interval.
• IO | I/O: file/stream encoding, quantization bits q_bits, channel mapping.
• SEC | Security & access: masks/policy enums, minimal exposure levels.

Composite parameters take the primary category as CAT, and list auxiliary categories in tags[] (e.g., primary CAL + tag GEO).

III. Naming & Coding

1. Parameter card ID: param_id = "<CAT>-<two-digit>-<optional-shortname>", e.g., CAL-01-τ_sys; unique registry key.
2. Symbol: use international short forms (c_ref, λ_ref, τ_sys, n_eff); avoid ALL-CAPS words.
3. Field style: identifiers/columns in snake_case; units/dimensions in SI/international symbols.
4. Aliases & deprecation:
   • List aliases in aliases[] for internal resolution only; external publications must use symbol.
   • Deprecate via status: "deprecated" and provide replaced_by; keep for one minor version cycle.
5. Path conventions: parameters coupled to path quantities (e.g., n_eff(ell), path weights) must carry delta_form and annotate gamma(ell)/d ell.
6. Conflict names: T_fil ≠ T_trans, n ≠ n_eff; forbid bare c, T, n.
7. Versioning: card versions use SemVer; version is mandatory and updated per registration change.

IV. Coding Rules (details)

• CAT set: PHY|CAL|ALG|ENV|GEO|TIM|IO|SEC.
• Index: two-digit ascending (01–99) per category; reserve 00.
• Shortname: optional, ASCII letters/underscore, length ≤ 16; recommend readable abbreviation consistent with symbol.
• Derivation chain: declare derived relations under constraints.derived, e.g., τ_sys = τ_base + α_T·ΔT; for cross-card deps, add depends_on[].
• Covariance grouping: cov_group ∈ {"timing","optics","medium","algo","env","geo"} for block structures in uncertainty composition.
• Freshness: calibration/environment-sensitive parameters must set freshness.valid_to and policy{tau_calib_s_max, clock_state}.

V. Normative Examples (valid)

# 1) Metrology/Calibration: system delay

version: "1.0.1"

param_id: "CAL-01-τ_sys"

name: "system_delay"

symbol: "τ_sys"

domain: { type: "real", unit: "s", range: [0, 1e-3], default: 1.0e-6, precision: "float64" }

lineage: { source_type: "measured", method: "loopback", instrument: "DPO-7k", calib_run_id: "CAL2025-09-24-01" }

freshness: { valid_from: "2025-09-24T00:00:00Z", valid_to: "2025-10-24T00:00:00Z",

policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "A", estimate: 2.0e-8, distribution: "normal", coverage: { k: 2 } }

constraints: { depends_on: ["TEMP"], derived: "" }

cov_group: "timing"

status: "stable"

see: ["Metrology.Sync v1.0:PPS","EFT.WP.Core.Metrology v1.0:check_dim"]

# 2) Medium/Path: effective refractive index profile

version: "1.0.0"

param_id: "PHY-03-n_eff_profile"

name: "effective_index_profile"

symbol: "n_eff(ell)"

domain: { type: "array", unit: "1", range: [0.8, 2.5], precision: "float64" }

lineage: { source_type: "derived", method: "kernel_fit", instrument: "—", calib_run_id: "—" }

freshness: { valid_from: "2025-09-24T00:00:00Z", valid_to: "2026-09-24T00:00:00Z", policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "A/B", estimate: 3.0e-3, distribution: "gaussian", coverage: { k: 2 } }

constraints: { depends_on: ["ENV-01-α_T","ENV-02-ΔT"], derived: "" }

path:

gamma: "gamma(ell)" # explicit path

measure: "d ell" # explicit measure

delta_form: "general" # or "factored"

cov_group: "medium"

tags: ["coherence_window"]

status: "stable"

see: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

# 3) Algorithm hyperparameter: Huber loss δ

version: "1.0.0"

param_id: "ALG-05-huber_delta"

name: "huber_delta"

symbol: "δ_huber"

domain: { type: "real", unit: "1", range: [0.1, 5.0], default: 1.345, precision: "float64" }

lineage: { source_type: "configured", method: "benchmark", instrument: "—", calib_run_id: "—" }

freshness: { valid_from: "2025-01-01T00:00:00Z", valid_to: "9999-12-31T23:59:59Z", policy: { tau_calib_s_max: 86400, clock_state: "locked" } }

uncertainty: { type: "B", estimate: 0.0, distribution: "degenerate", coverage: { k: 2 } }

constraints: { depends_on: [], derived: "" }

cov_group: "algo"

status: "stable"

see: ["ErrorBudget.Template v1.0:Ch.6","PTN.Template v1.0:Ch.7"]

VI. Aliases, Deprecation & Rollback

• Aliases: aliases[] for legacy scripts/imports only; publications must use symbol.
• Deprecation: set status: deprecated and replaced_by; keep for one minor version; mark in report_manifest.yaml.
• Rollback: use I27-lock_version(param_id, semver) to tag immutable points for audit traceability.

VII. Gate Mapping

• G2 Citation compliance: see[]/references[] use volume+version+anchor, anchor coverage ≥ 90%.
• G4 Dimensional closure: domain.unit and derived relations pass I70-dim_check; p_dim = 1.0.
• G5 Freshness: parameters with freshness must be within validity; else Restricted or recalibrate.
• G8 Uniqueness: param_id and checksum must be unique.

VIII. Schema & Validation

{

"$schema": "https://json-schema.org/draft/2020-12/schema",

"title": "param_card v1.0.0",

"type": "object",

"required": ["param_id","symbol","domain","status","version","see"],

"properties": {

"param_id": {"type": "string","pattern":"^[A-Z]{3}-\\d{2}(-[A-Za-z_]{1,16})?$"},

"symbol": {"type": "string"},

"domain": {

"type":"object",

"required":["type","unit"],

"properties":{"type":{"enum":["real","integer","enum","array","tensor"]},"unit":{"type":"string"}}

},

"status":{"enum":["draft","stable","deprecated"]},

"see":{"type":"array","items":{"type":"string"}, "minItems":1}

}

}

IX. Cross-References

• With Ch. 4 (Domains, Units & Defaults) for unit/dimension & validity checks.
• With Ch. 5 (Lineage & Traceability) for lineage.
• With Error Budget Card (Ch. 5/8/9) for cov_group & gate mapping.
• With PTN Template (Ch. 5/11) for data contract & publication page.

X. Checklist

• param_id = "<CAT>-<two-digit>-<optional-shortname>" unique and regex-validated.
• symbol uses international short form; no conflict or bare symbols.
• Path-related parameters explicitly show gamma(ell)/d ell and record delta_form; p_dim = 1.0.
• domain/unit/range/default/precision complete; lineage/freshness/policy defined.
• cov_group, uncertainty, and constraints.depends_on/derived recorded; see[]/version compliant with anchor coverage ≥ 90%.
• Deprecation/replacement and rollback (lock version) set; registry checksum unique.