03-EFT.WP.Core.Parameters v1.0 | Chapter 1 — Parameter System and Numbering

Home ／ Docs-Technical WhitePaper ／ 03-EFT.WP.Core.Parameters v1.0

Chapter 1 — Parameter System and Numbering

I. Naming Postulates and Hierarchical Conventions (P31-1…P31-3)

• P31-1 (Uniqueness): every parameter uses code as a globally unique key; once released, it must not be reused for a different meaning.
• P31-2 (Stability): the semantics and dimensions of a code are invariant; defaults and prior hyper-parameters may change in minor versions but must be recorded in Appendix B.
• P31-3 (No ambiguous prefixes): role prefixes and family names must not form mutually referential chains; aliases may map only one-way to a single canonical code.
• R31-1 (First-occurrence discipline): declare unit and the valid domain at the first occurrence; cross-section references must use the code only.
• R31-2 (Path/arrival parameters): any parameter tied to path/arrival must write gamma(ell) and d ell, and must use the fully parenthesized form T_arr = ( ∫ ( n_eff / c_ref ) d ell ).
• R31-3 (Conflict isolation): never mix T_fil with T_trans, or n with n_eff; never use bare c (use c_ref).

II. Roles and Numbering Families

1. Role set (role)
   • obs: observation-layer parameters (noise, calibration, sampling).
   • proc: process/dynamics (transport, sources/sinks, couplings).
   • const: constitutive/mapping hyper-parameters of F_map(•).
   • num: numerical algorithm and solver parameters.
   • env: environment/scenario baselines (e.g., c_ref, background density).
   • drv: derived parameters (declared via derive_param dependencies).
2. Role ordering
   • Ordering table: const < env < proc < obs < num < drv.
   • When assembling theta, sort by the role order above, then lexicographically by code, to guarantee cross-implementation consistency.

III. code Syntax and Allowed Characters

1. Grammar
   code ::= role "." family "." name [ "." scale ] [ "@" scenario ] [ "#v" semver ]
   Example: proc.transport.kappa, const.n_eff.alpha0@baseline#v1.0
2. Constraints
   • role ∈ {obs,proc,const,num,env,drv}.
   • family, name, scale, scenario use [a-z0-9_]+; uppercase and whitespace are disallowed.
   • semver follows MAJOR.MINOR[.PATCH]; it may be omitted at release time; versioning is maintained by bump_version.
3. Correct examples
   obs.arrival.sigma_Tarr, num.solver.tol_newton, env.c_ref.si
4. Incorrect examples
   • process.kappa (missing three-segment pattern)
   • PROC.Transport.Kappa (invalid casing)
   • const.neff.alpha (missing underscore; must be n_eff)

IV. Parameter Vectors and Grouping

1. Notation and relations
   • theta (full parameter vector), theta_g (a parameter group), theta_fix (frozen set), theta_free (identifiable set).
   • theta = [ theta_free ; theta_fix ] (concatenate in the role order of §II, then lexicographic).
2. Group construction
   • Set-builder: theta_free def= { code ∈ Theta | trainable(code) }.
   • Group operations ∪, ∩, \ are realized as ordered lists with stable ordering.

V. Aliases and Normalization

1. Alias rules
   • Aliases exist solely for legacy/third-party compatibility; do not create multi-source synonyms.
   • After add_alias(canonical, alias), normalize_param(alias) -> canonical must hold identically.
2. Conflict handling
   If any alias conflicts with an existing code or alias, reject and document the resolution (retain/deprecate) in the change log.

VI. Versioning, Scenarios, and Lifecycle

1. Scenario governance
   Manage the @scenario fragment via create_scenario / activate_scenario, allowing the same code to hold different defaults or priors per scenario.
2. Lifecycle
   • Freeze/thaw: freeze(code), thaw(code); frozen parameters are automatically included in theta_fix.
   • Deprecation: mark with deprecated: true in exports and provide a migration target see: [canonical].

VII. Dimensions, Units, and Non-Dimensional Mapping

• Dimensional closure
  On first registration, declare unit and validate with check_dim(expr) against the reference scales L0, t0, T0.
• Non-dimensionalization
  Example: bar_kappa def= kappa * ( t0 / L0^2 ), where kappa has dimension [L]^2/[T].
• Arrival-time–coupled parameters
  Any parameter that affects T_arr (e.g., c_ref, hyper-parameters of the n_eff family) must co-declare the path and use T_arr = ( ∫ ( n_eff / c_ref ) d ell ).

VIII. Numbering Cards and Templates

• Naming card (excerpt)
  role: see §II; family: sub-domain or component; name: dimensional or statistical object; scale: optional scale tag (e.g., si, normL0).
• Citation template
  In-text: see ["S20-1","I30 5"]; cross-volume fixed form: “see companion white paper Energy Threads, Chapter x, S/P/M/I…”.

IX. Registration Examples (I30 — 1, 5 items)

• Example 1
  register_param(name="Reference propagation speed", code="env.c_ref.si", type="scalar", unit="m/s", role="env", default=2.99792458e8, bounds=(1e8, 4e8), prior={"family":"LogNormal","hyper":{"mu":19.5,"sigma":0.05}}, transform=None, see=["S20-1","Core.Terms:c_ref"])
• Example 2
  register_param(name="Transport diffusivity", code="proc.transport.kappa", type="scalar", unit="m^2/s", role="proc", default=1.0e-3, bounds=(1.0e-6, 1.0), prior={"family":"LogNormal","hyper":{"mu":-6.9,"sigma":1.0}}, transform="log", see=["S50-1"])
• Example 3
  register_param(name="Effective index offset", code="const.n_eff.alpha0", type="scalar", unit="1", role="const", default=0.0, bounds=(-0.5, 0.5), prior={"family":"Normal","hyper":{"mu":0.0,"sigma":0.1}}, transform=None, see=["S30-1","Core.Terms:n_eff"])
• Example 4
  register_param(name="Arrival-time noise stdev", code="obs.arrival.sigma_Tarr", type="scalar", unit="s", role="obs", default=1.0e-4, bounds=(1.0e-6, 1.0), prior={"family":"HalfNormal","hyper":{"sigma":1.0}}, transform="log", see=["S20-2"])
• Example 5
  register_param(name="Newton solver tolerance", code="num.solver.tol_newton", type="scalar", unit="1", role="num", default=1.0e-8, bounds=(1.0e-12, 1.0e-2), prior=None, transform="log", see=["I20 3"])
• Alias example
  add_alias(canonical="proc.transport.kappa", alias="kappa_T"); normalize_param("kappa_T") -> "proc.transport.kappa"

X. Validation Checklist (Lint & Consistency)

• Role and three-segment rule: code must match role.family.name; optional scale / @scenario / #v must sit at the end in fixed order.
• Casing and charset: only lowercase letters, digits, and underscores; spaces and hyphens are forbidden.
• Conflicts and aliases: the code and alias namespaces are mutually exclusive; each alias must point to exactly one canonical.
• Dimensional closure: unit must agree with check_dim; dimensionless quantities use "1".
• Arrival-time references: whenever T_arr appears, the text must include gamma(ell) and d ell and use the integrand ( n_eff / c_ref ).
• Symbol isolation: never interchange T_fil ↔ T_trans or n ↔ n_eff; never use bare c.
• Assembly order: the concatenation order of theta follows §II plus lexicographic; export theta_free and theta_fix with explicit ordering.

XI. Cross-Volume Anchors and Example Citations

• Anchors referenced here: c_ref, n_eff(x,t), T_arr, gamma(ell), d ell (see Core.Terms and Core.Equations S20-, S30-).
• Typical citation form
  see=["S20-1","S30-1","S50-1","I20 3","Core.Terms:n_eff"]

XII. Summary and Forward Link

• We established the three naming postulates (P31-1…P31-3), the role taxonomy, and the code syntax, and defined the assembly and lifecycle of theta / θ.
• Next: move to the catalog and entry specification, constructing a searchable parameter registry organized by const / proc / obs / num / env / drv, with cross-volume citations.