10-EFT.WP.Core.Tension v1.0 | Appendix E Interface Reference (I70)

Home ／ Docs-Technical WhitePaper ／ 10-EFT.WP.Core.Tension v1.0

Appendix E Interface Reference (I70)

I. Scope and Conventions

• This appendix defines the I70-* interface signatures, parameters, returns, and error semantics, covering geometry/materials, statics, dynamics and waves, interfacial tension, junctions and transmission, arrival-time calibration, and uncertainty & information bounds.
• Units, symbols, and measures follow Appendix A and the Mathematical Expression Ambiguity-Avoidance Rules. Any quantity involving an integral or a path must explicitly specify gamma(ell) and the measure d ell.
• All interface parameter names and return field names use English plain text. Cross-references to S72-* and Mx-7* are annotated at the point of use.
• Type notation: PathRef, MatRef, TensionFieldRef, WaveRef, NetRef are immutable handles; scalar values use float; sequences use array[float]; mappings use dict.

II. Core Types and Common Fields

1. PathRef
   • Description: reference to a line geometry that carries gamma(ell) and discretized nodes.
   • Metadata: id:str, nodes:array[[x,y,z]], metric:str, L_gamma:float.
2. MatRef
   • Description: cross-section and material properties bound to a path.
   • Fields: A:float (m^2), rho_m:float (kg/m^3), rho_l:float (kg/m), E:float (Pa).
3. TensionFieldRef
   • Description: tension and displacement fields along ell.
   • Fields: T_fil:array[float] (N), u:array[float] (m), epsilon:array[float].
4. WaveRef
   • Description: time- or frequency-domain wave solution.
   • Fields: c:array[float] (m/s), accessors for u(t,ell) or U(omega,ell), Z:array[float] (kg/s).
5. NetRef
   • Description: network/node solution and scattering quantities.
   • Fields: Z_ports:array[float], S_matrix:array[array[complex]], balance:dict.

III. I70-1 Geometry & Attributes

1. define_path(nodes:any, metric:str|None=None, base:str="euclid") -> PathRef
   • Inputs
     1. nodes: array[[x,y,z]] or spline control points with arc-length parameterization.
     2. metric: "euclid", "geo", or a user metric name; defaults to base.
     3. base: reference space; default "euclid".
   • Returns
     PathRef with L_gamma = ( ∫ 1 d ell ) and node arc-length parameterization.
   • Constraints
     Number of nodes ≥ 2; L_gamma > 0. If parameterized as ell = ell(s), output must include | d ell / ds | (per rules).
   • Related
     Data formats and frames: see Appendix B.
2. assign_section(path:PathRef, A:float, rho_m:float, E:float) -> MatRef
   • Inputs
     A, rho_m, E in SI per Appendix A; internally derive rho_l = rho_m * A.
   • Returns
     MatRef bound to path.
   • Constraints
     A > 0, rho_m > 0, E > 0.
   • Related
     Use with S72-2, S72-5 for 1D elasticity and waves.

IV. I70-2 Static Tension & Constitutive Laws

1. tension_static(path:PathRef, loads:any, bc:any, law:str="hooke") -> TensionFieldRef
   • Inputs
     1. loads: distributed loads q(ell) and sets of concentrated loads.
     2. bc: boundary-condition set (Dirichlet/Neumann/Robin; see Appendix C).
     3. law: "hooke" or user-defined constitutive law.
   • Returns
     TensionFieldRef containing T_fil(ell), u(ell), epsilon(ell).
   • Math
     Balance S72-1 : ∂_ell T_fil + q_tan = 0; constitutive S72-2.
   • Audits
     End tractions consistent with internal forces within tolerance; elastic energy path_energy per S72-8.
2. stress_to_tension(sigma:any, A:float, orientation:any) -> float
   • Inputs
     sigma: sigma_ij or scalar sigma; orientation: section normal and axial direction.
   • Returns
     Axial tension T_fil = ( sigma : (t_hat ⊗ t_hat) ) * A.
   • Units
     Pa * m^2 = N.

V. I70-3 Dynamics & Waves

1. string_wave_solve(path:PathRef, T:callable|float, rho_l:callable|float, bc:any, damping:any|None=None) -> WaveRef
   • Inputs
     1. T: constant T0 or approximation to T_fil(ell,t) with space/time dependence.
     2. rho_l: constant or function.
     3. bc: terminal and interior junction boundary conditions (Appendix C).
     4. damping: optional dict{ c_visc , eta_struc }.
   • Returns
     WaveRef with c(ell) = sqrt( T_fil / rho_l ) and impedance Z = rho_l * c.
   • Math
     S72-5 : rho_l ∂_tt u = ∂_ell( T_fil ∂_ell u ) + q; uniform case S72-6.
   • Stability
     Explicit stepping must satisfy S72-12 : Δt ≤ CFL * ( Δell / c_max ), or use implicit/spectral schemes.
2. estimate_tension_from_modes(freqs:any, L:float, rho_l:float) -> float
   • Inputs
     freqs: fundamental or several modal frequencies f_n; L equals L_gamma; rho_l line density.
   • Returns
     Estimated tension T_fil.
   • Model
     Simply supported string approximation f_n = ( n / (2L) ) * sqrt( T_fil / rho_l ); invert T_fil via least squares (record boundary type).

VI. I70-4 Interfacial Tension & Curvature

1. young_laplace(sigma_s:float|callable, kappa1:float, kappa2:float) -> float
   • Returns
     Pressure jump Δp = sigma_s * ( kappa1 + kappa2 ) (S72-3).
   • Notes
     If sigma_s varies with position/curvature, evaluate at the call site.
2. capillary_wave_dispersion(sigma_s:float, rho:float, k:float, g:float|None=None) -> float
   • Returns
     Dispersion omega(k); default without gravity omega = sqrt( ( sigma_s / rho ) * k^3 ); with gravity omega = sqrt( g*k + ( sigma_s / rho ) * k^3 ).
   • Units
     omega in rad/s.

VII. I70-5 Junctions & Transmission

1. junction_solve(network:any, impedances:any, bc:any) -> NetRef
   • Inputs
     1. network: port/node topology and connection matrix.
     2. impedances: branch/port Z_i(omega) or time-domain equivalents.
     3. bc: incidence/excitation specification and open/matched terminations.
   • Returns
     NetRef with S_matrix, port balances, and power flows.
   • Math
     Node balance S72-7; lossless nodes yield unitary S_matrix; multi-port scattering derivation: Appendix D §XII.
2. transmission_coeff(Z1:float, Z2:float) -> dict
   • Inputs
     Z1, Z2: characteristic impedances of adjacent media/branches.
   • Returns
     dict{ r_amp:float , t_amp:float , R_ref:float , T_trans:float }.
   • Math
     S72-9 : r_amp = ( Z2 - Z1 ) / ( Z2 + Z1 ); S72-10 : t_amp = 2 * Z2 / ( Z1 + Z2 ); S72-11 (power conservation).

VIII. I70-6 Calibration & Arrival Time

1. calibrate_tension_by_toa(trace:any, L_gamma:float, rho_l:float, n_eff:any|None=None, c_ref:float|None=None) -> float
   • Inputs
     1. trace: waveform or timestamp set sufficient for TOA extraction; must contain T_arr or a rule to compute it.
     2. L_gamma: path arc length; rho_l: line density; optional n_eff, c_ref for two-convention consistency logging.
   • Returns
     T_fil = rho_l * ( L_gamma / T_arr )^2 (S72-14).
   • Record
     Also output/log delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) | (gauge consistency).
2. enforce_arrival_time_convention(trace:any) -> None
   • Function
     Align the input trace to the unified TOA convention (peak, energy centroid, or first-slope threshold) and write metadata toa_convention.
   • Related
     Aligned with the arrival-time chapter in Core.Density.

IX. I70-7 Uncertainty & Bounds

1. fisher_information_tension(model:any, theta:dict) -> matrix
   • Inputs
     model: likelihood or measurement operator; theta: parameter map containing at least T_fil, optionally rho_l, L_gamma, noise variance, etc.
   • Returns
     Fisher information matrix I_F(theta) (S72-15).
   • Example
     Single-parameter TOA: I_F(T_fil) = ( (∂_{T_fil} T_arr)^2 ) / sigma_T^2; see Appendix D §XIII for ∂_{T_fil} T_arr.
2. crlb_tension(model:any, theta:dict) -> matrix
   • Returns
     Cramér–Rao lower bound cov(theta) ≥ I_F^{-1}(theta) (S72-16).
   • Constraints
     Requires invertible I_F; if degenerate, return pseudoinverse and mark rank_deficient=True.

X. Error Model and Return Conventions

1. Generic return wrapper (enhanced mode)
   dict{ ok:bool , data:any|None , err_code:str|None , err_msg:str|None , diag:dict|None }.
2. Standard error codes
   • E_GEOM_INVALID (degenerate geometry or L_gamma ≤ 0)
   • E_UNIT_MISMATCH (unit/dimension inconsistency)
   • E_BC_INCOMPAT (incompatible boundary conditions)
   • E_STAB_VIOLATION (violates S72-12 stability)
   • E_NONCONVERGE (nonlinear or solver non-convergence)
   • E_SINGULAR_IF (singular I_F)
3. Suggested diagnostics
   • energy_balance (ΔE and relative error)
   • residual_norm (equilibrium residual)
   • cfl_ratio = Δt * c_max / Δell (should be ≤ CFL)
   • delta_form (two-convention TOA gap)

XI. Mandatory Unit & Dimension Audits (Interface Level)

1. Before solving, automatically execute
   • check_dim( T_fil ) = N
   • check_dim( sigma_s ) = N/m
   • check_dim( sigma_ij ) = Pa
   • check_dim( Z ) = kg/s
2. On failure, raise E_UNIT_MISMATCH and report expected versus actual unit pairs.

XII. QA Use Cases (Mapped to Mx-79)

• Geometry & attributes
  Produce baseline PathRef and MatRef; verify L_gamma and rho_l = rho_m * A.
• Statics
  tension_static under uniform load versus analytical catenary approximation or 1D elastic closed forms; audit S72-1 residual and S72-8 energy.
• Dynamics
  string_wave_solve versus S72-6 modal frequencies; explicit stepping checked by S72-12.
• Junctions
  transmission_coeff satisfies R_ref + T_trans = 1 (lossless); junction_solve unitarity.
• Calibration
  calibrate_tension_by_toa recovers T_fil on synthetic waveforms and logs delta_form.
• Information bounds
  fisher_information_tension and crlb_tension lower bounds versus Monte-Carlo variance under known noise.

XIII. Data Exchange and Schema Pointers (Aligned with Appendix B)

• Geometry carrier
  path.json: { "nodes":[[x,y,z],...], "metric":"euclid", "L_gamma":float }
• Materials carrier
  section.json: { "A":float, "rho_m":float, "rho_l":float, "E":float }
• Loads & boundaries
  loads_bc.json: { "q":[ [ell,value], ... ], "bc":[ {"type":"Dirichlet","at":"left","u":0.0}, ... ] }
• Dispersion/impedance
  ports.json: { "Z":[ {"port":1,"value":float}, ... ] }

XIV. Versioning, Compatibility, and Deprecation Strategy

• Version fields
  All returned objects include api_version:"I70" and schema_version:"TEN/1.0".
• Compatibility
  Minor versions may add fields with backward compatibility; deletions or semantic changes are listed under deprecations and retain at least one minor-version grace period.
• Immutability
  All *Ref handles are read-only; modifications occur via corresponding assign_* or by creating new objects.

XV. Symbol & Formula Anchors (Inline Implementation Audits)

1. Implementations should log anchors for S72-1 through S72-16 as anchor:"S72-*", value:... for cross-volume traceability.
2. Key conservation checks
   • R_ref + T_trans = 1 (lossless junction)
   • path_energy ≥ 0 (non-negative elastic energy)
   • Continuous logging of delta_form with threshold alerts during calibration.

XVI. Minimal Example (Signatures & Call Order)

1. Geometry & materials
   • p = define_path(nodes, metric="euclid")
   • m = assign_section(p, A, rho_m, E)
2. Static audit
   tf = tension_static(p, loads, bc, law="hooke")
3. Dynamics & impedance
   • w = string_wave_solve(p, T=tf.T_fil or T0, rho_l=m.rho_l, bc=bc)
   • Z1 = w.Z[0]; Z2 = Z_match
   • coeff = transmission_coeff(Z1, Z2) (audits S72-9–S72-11)
4. Arrival time & tension calibration
   T_est = calibrate_tension_by_toa(trace, L_gamma=p.L_gamma, rho_l=m.rho_l, n_eff=n_eff, c_ref=c_ref)
5. Information bounds
   • IF = fisher_information_tension(model, {"T_fil":T_est, "sigma_T":sigma_T})
   • CR = crlb_tension(model, {"T_fil":T_est, "sigma_T":sigma_T})

XVII. Dependencies and External Constraints

• Frequency-domain interfaces and spectral density S_xx(f) follow Core.Sea; the two arrival-time conventions follow Core.Density; curvature metrology follows Core.Metrology.
• t_hat, n_hat, and the measures d ell, dA must comply with coordinate and meshing specifications in Appendix B.