ANYfeSolver 0.5.0a1__py3-none-any.whl

anyfesolver/_native_guard_dispatch.py

@@ -0,0 +1,140 @@
+"""Optional expected-fact accelerator. Every decline uses the literal guard."""
+import base64
+import csv
+import hashlib
+import importlib
+import importlib.metadata
+import os
+from pathlib import Path
+import platform
+import sys
+import types
+
+_MODULE_TYPE=types.ModuleType
+_BUILTIN_FUNCTION_TYPE=types.BuiltinFunctionType
+_MODULES=sys.modules
+_DICT_TYPE=dict
+_STATE=None
+_COUNTERS=[0,0]  # Diagnostic values only; the owned container identity is fixed.
+
+def initialise(classes,helpers,missing,literal_roots):
+    global _STATE
+    if _STATE is not None:
+        raise RuntimeError('native guard already initialised')
+    if (sys.platform!='win32' or sys.version_info[:2]!=(3,11)
+            or platform.machine().upper() not in ('AMD64','X86_64')
+            or os.environ.get('ANYSOLVER_NATIVE_GUARD')=='python'):
+        _STATE=('fallback','unsupported_abi_or_explicit_python')
+        return
+    try:
+        module=importlib.import_module('anyfesolver._native_guard')
+    except ModuleNotFoundError as error:
+        if error.name!='anyfesolver._native_guard':
+            raise
+        _STATE=('fallback','extension_absent')
+        return
+    except ImportError as error:
+        _STATE=('refusal',str(error))
+        return
+    try:
+        if type(module) is not _MODULE_TYPE:
+            raise ValueError('native module type changed')
+        if any(type(key) is not str for key in module.__dict__):
+            _STATE=('fallback','unsupported_native_namespace')
+            return
+        names=('make_plan','compare','build_info','binary_identity','entry_identity','statistics','reset_statistics')
+        entries=tuple((name,module.__dict__[name]) for name in names)
+        # Do not call a module-supplied proof function until every entry is an
+        # actual C builtin owned by this exact native module. Python functions
+        # cannot manufacture an entry/image proof at cold admission.
+        if any(type(entry) is not _BUILTIN_FUNCTION_TYPE or entry.__self__ is not module or entry.__name__!=name
+               for name,entry in entries):
+            raise ValueError('native entries are not canonical module-owned C functions')
+        identity=module.entry_identity
+        entry_facts=tuple((name,entry,identity(entry),entry.__module__) for name,entry in entries)
+        if any(facts is NotImplemented or facts[0]!=name or facts[1] is not module for name,_,facts,_ in entry_facts):
+            raise ValueError('native entry ownership mismatch')
+        image=module.binary_identity()
+        api,abi,source_sha=module.build_info()
+        if api!=1 or abi!='cp311-win_amd64' or image is NotImplemented:
+            raise ValueError('native build ABI mismatch')
+        mapped=Path(image[0]).resolve(strict=True)
+        if mapped.parent!=Path(__file__).resolve().parent or mapped.suffix.lower()!='.pyd':
+            raise ValueError('mapped native image is outside the owning package')
+        binary_sha=hashlib.sha256(mapped.read_bytes()).hexdigest()
+        source=Path(__file__).with_name('_native_guard.cpp')
+        if hashlib.sha256(source.read_bytes()).hexdigest()!=source_sha:
+            raise ValueError('native compiled source identity mismatch')
+        distribution=importlib.metadata.distribution('ANYfeSolver')
+        record=distribution.read_text('RECORD')
+        if record is None:
+            _STATE=('fallback','unadmitted_no_binary_record')
+            return
+        matches=[]
+        for member,digest,size in csv.reader(record.splitlines()):
+            if Path(distribution.locate_file(member)).resolve()==mapped:
+                matches.append((digest,size))
+        expected='sha256='+base64.urlsafe_b64encode(bytes.fromhex(binary_sha)).decode().rstrip('=')
+        if not matches:
+            # Editable/source layouts may build a valid in-place extension but
+            # do not record it in installed wheel metadata. Never fast-pass an
+            # unrecorded binary; the complete literal guard remains available.
+            _STATE=('fallback','unadmitted_no_binary_record')
+            return
+        if len(matches)!=1 or matches[0]!=(expected,str(mapped.stat().st_size)):
+            raise ValueError('mapped native binary does not match installed wheel RECORD')
+        plan=module.make_plan(classes,helpers,missing,literal_roots)
+        if plan is NotImplemented:
+            _STATE=('fallback','unsupported_expected_grammar')
+            return
+        attributes=tuple((name,module.__dict__.get(name)) for name in ('__name__','__spec__','__loader__','__package__','__file__'))
+        _STATE=('native',module,plan,entry_facts,image,(api,abi,source_sha),binary_sha,str(mapped),attributes)
+    except (KeyError,ValueError,OSError,importlib.metadata.PackageNotFoundError) as error:
+        _STATE=('refusal',str(error))
+
+def try_compare(classes,helpers):
+    state=_STATE
+    if state[0]=='fallback':
+        _COUNTERS[0]+=1
+        return NotImplemented
+    if state[0]!='native':
+        return 2
+    _,module,plan,entries,image,build,binary_sha,path,attributes=state
+    if (type(module) is not _MODULE_TYPE or type(sys) is not _MODULE_TYPE
+            or type(_MODULES) is not _DICT_TYPE):
+        return 2
+    if any(type(key) is not str for key in sys.__dict__) or any(type(key) is not str for key in _MODULES):
+        return NotImplemented
+    if sys.__dict__.get('modules') is not _MODULES or _MODULES.get('anyfesolver._native_guard') is not module:
+        return 2
+    namespace=module.__dict__
+    if any(type(key) is not str for key in namespace):
+        return NotImplemented
+    for name,value in attributes:
+        if namespace.get(name) is not value:
+            return 2
+    # Exact native module dictionary: no custom getattr is called here.
+    for name,entry,facts,label in entries:
+        if namespace.get(name) is not entry or entry.__module__ is not label:
+            return 2
+    identity=entries[4][1]
+    for name,entry,facts,label in entries:
+        if identity(entry)!=facts:
+            return 2
+    if entries[2][1]()!=build:
+        return 2
+    result=entries[1][1](plan,classes,helpers)
+    if result is True:
+        _COUNTERS[1]+=1
+    elif result is False or result is NotImplemented:
+        _COUNTERS[0]+=1
+    return result
+
+def diagnostics():
+    state=_STATE
+    result={'backend':state[0] if state else 'uninitialised','python_fallbacks':_COUNTERS[0],'native_passes':_COUNTERS[1]}
+    if state and state[0]=='native':
+        result.update(binary_sha256=state[6],mapped_image=state[7],build=state[5],native=state[3][5][1]())
+    elif state:
+        result['reason']=state[1]
+    return result

anyfesolver/_native_large_factor_chain.py

@@ -0,0 +1,55 @@
+"""Sparse exact integer products; reassociate before dense modal congruence.
+
+No binary64 Gram matrix is formed. Integer products/sums are exact, and each
+final projected entry is rounded once, as in the historical implementation.
+"""
+from math import fsum
+import numpy as np
+from ._dyadic_bilinear import _Matrix,_capture,_transpose,_add,_rounded
+
+
+def multiply(a,b,checkpoint):
+    if len(a.rows[0])!=len(b.rows):raise ValueError('matching exact factor dimensions')
+    left=[tuple((k,x) for k,x in enumerate(row) if x) for row in a.rows]
+    columns=tuple(zip(*b.rows))
+    right=[tuple((k,x) for k,x in enumerate(col) if x) for col in columns]
+    rows=[]
+    for i,row in enumerate(left):
+        checkpoint();values=[]
+        for j,col in enumerate(right):
+            if len(row)<=len(col):value=sum(x*columns[j][k] for k,x in row)
+            else:value=sum(a.rows[i][k]*x for k,x in col)
+            values.append(value)
+        rows.append(tuple(values))
+    return _Matrix(tuple(rows),a.power+b.power)
+
+
+def gram(a,checkpoint):
+    width=len(a.rows[0]);rows=[[0]*width for _ in range(width)]
+    for row in a.rows:
+        checkpoint();items=[(i,x) for i,x in enumerate(row) if x]
+        for k,(i,x) in enumerate(items):
+            for j,y in items[k:]:rows[i][j]+=x*y
+    for i in range(width):
+        for j in range(i):rows[i][j]=rows[j][i]
+    return _Matrix(tuple(map(tuple,rows)),2*a.power)
+
+
+def reassemble(left,right,g,b,mapping,checkpoint):
+    ll,rr,gg,bb,v=(_capture(a,checkpoint) for a in (left,right,g,b,mapping))
+    material=gram(multiply(ll,rr,checkpoint),checkpoint)
+    signed=_add(material,gg);mass=gram(bb,checkpoint)
+    vt=_transpose(v)
+    h=multiply(vt,multiply(signed,v,checkpoint),checkpoint)
+    m=multiply(vt,multiply(mass,v,checkpoint),checkpoint)
+    checkpoint();return _rounded(h),_rounded(m)
+
+
+def sparse_float_product(a,b,dot_terms,checkpoint):
+    rows=[];columns=b.T
+    for row in a:
+        checkpoint();indices=np.flatnonzero(row);values=[]
+        left=row[indices]
+        for column in columns:values.append(fsum(dot_terms(left,column[indices])))
+        rows.append(values)
+    return np.array(rows)

anyfesolver/_native_material_protocol.py

@@ -0,0 +1,51 @@
+"""Internal opt-in station-state validation for native nonlinear elements.
+
+No mechanics, default routing, or implicit registration lives here. Validators
+operate on owned state copies before the store publishes accepted history.
+"""
+
+from dataclasses import dataclass, fields
+from typing import Any, Callable
+
+import numpy as np
+
+
+PROTOCOL = "ANY_NATIVE_MATERIAL_VALIDATION_V1"
+
+
+@dataclass(frozen=True)
+class NativeMaterialValidator:
+    validate: Callable[..., None]
+
+    def __post_init__(self) -> None:
+        if not callable(self.validate):
+            raise TypeError("Native material validation requires a callable")
+
+
+@dataclass(frozen=True)
+class NativeMaterialContext:
+    """Live solver-owned authority, unlike a detached immutable rotation view."""
+
+    store: Any
+    token: Any
+    element_id: int
+    node_ids: tuple[int, ...]
+    reference_directors: np.ndarray
+
+    def require_view(self, view: Any) -> None:
+        issued = self.store.native_material_context(self.token, self.element_id)
+        if (self.node_ids != issued.node_ids
+                or not np.array_equal(self.reference_directors, issued.reference_directors)):
+            raise ValueError("Native material context does not match the model binding")
+        fresh = self.store.native_element_rotation_view(
+            self.token, self.element_id, issued.node_ids, issued.reference_directors
+        )
+        if type(view) is not type(fresh):
+            raise ValueError("Native material context requires its exact rotation view")
+        for field in fields(fresh):
+            expected = getattr(fresh, field.name)
+            actual = getattr(view, field.name)
+            equal = (np.array_equal(actual, expected) if isinstance(expected, np.ndarray)
+                     else actual == expected)
+            if not equal:
+                raise ValueError("Detached or mismatched native material rotation view")

anyfesolver/_native_midpoint_controller.py

@@ -0,0 +1,90 @@
+"""Shared native midpoint trajectory transaction engine; no physics/codec."""
+from .control import cancellation_safe_point, SolveCancelled
+
+def advance(analysis, state, t_end, identity, contract, controller, native, token, published, adapter):
+    NativeTransientError = adapter.error
+    _RETRYABLE = adapter.retryable
+    _result = adapter.result
+    settings = contract['settings']
+    while state.time < t_end:
+        candidate = None
+        commit_endpoint = None
+        commit_attempted = False
+        try:
+            cancellation_safe_point(token, 'native_transient.before_step')
+            if controller['accepted_steps'] >= settings['max_steps']:
+                raise NativeTransientError('native trajectory accepted step budget exhausted')
+            planned = controller['next_dt']
+            remaining = float(t_end-state.time)
+            dt = min(planned, remaining)
+            truncated = remaining < planned
+            if not dt > 0 or not state.time+dt > state.time or state.time+dt > t_end:
+                raise NativeTransientError('requested native endpoint is not representable without overshoot')
+            failures = []
+            def receive_candidate(issued):
+                nonlocal candidate
+                candidate = issued
+            for cut in range(settings['max_cutbacks']+1):
+                candidate = None
+                try:
+                    analysis._prepare_trial(state, dt=dt, cancellation_token=token,
+                                            prepare=receive_candidate)
+                    if candidate is None:
+                        raise NativeTransientError('native trial did not provide its issued receipt')
+                    break
+                except ValueError as error:
+                    if candidate is not None:
+                        analysis._discard_prepared_trial(candidate)
+                        candidate = None
+                    if str(error) not in _RETRYABLE:
+                        raise
+                    failures.append(dict(dt=dt, reason=str(error)))
+                    if cut == settings['max_cutbacks'] or .5*dt < settings['minimum_dt']:
+                        raise NativeTransientError('native trajectory cutback budget/floor exhausted') from error
+                    dt *= .5
+            # Prepare ALL disposable work, accounting, controller/result bytes
+            # and native capsule before the one native commit. None of these
+            # objects is published as an accepted step until commit succeeds.
+            next_controller, next_native, prepared = adapter.prepare_step(
+                analysis, state, t_end, identity, contract, controller, candidate,
+                dt, failures, planned, truncated, settings, token)
+            cancellation_safe_point(token, 'native_transient.before_commit')
+            commit_endpoint = candidate.endpoint
+            commit_attempted = True
+            analysis.commit(candidate, cancellation_token=token)
+            # The native owner's visible endpoint, rather than a return value,
+            # is authoritative after its atomic commit has completed.
+            if analysis.current is not commit_endpoint:
+                raise NativeTransientError('native commit did not publish its issued endpoint')
+            state = commit_endpoint
+            controller, native, published = next_controller, next_native, prepared
+            candidate = None
+        except BaseException as error:
+            if commit_attempted and analysis.current is commit_endpoint:
+                # Commit may have completed before its caller is interrupted.
+                # Publish only bytes fully prepared before that authentic commit;
+                # never discard or roll back an already accepted native endpoint.
+                state = commit_endpoint
+                controller, native, published = next_controller, next_native, prepared
+                candidate = None
+            if candidate is not None:
+                try:
+                    analysis._discard_prepared_trial(candidate)
+                except BaseException as discard_error:
+                    if isinstance(error, Exception) and not isinstance(error, SolveCancelled):
+                        raise NativeTransientError('native candidate cleanup failed: '+str(discard_error),
+                            partial=published, native_checkpoint=native, accepted_state=state) from error
+                    error.cleanup_error = discard_error
+            if isinstance(error, SolveCancelled):
+                error.partial = published
+                error.native_checkpoint = native
+                error.accepted_state = state
+                raise
+            if not isinstance(error, Exception):
+                error.partial = published
+                error.native_checkpoint = native
+                error.accepted_state = state
+                raise
+            raise NativeTransientError(str(error), partial=published,
+                native_checkpoint=native, accepted_state=state) from error
+    return published

anyfesolver/_native_modal_capacity.py

@@ -0,0 +1,26 @@
+"""Explicit bounded larger factor domain; historical defaults are unchanged."""
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+POLICY='GE_BEAM3_LARGE_EXACT_FACTOR_MODAL_CAPACITY_V1'
+_ACTIVE=ContextVar('native_large_factor_modal_capacity',default=False)
+
+def limits():
+    return (640,12288,640) if _ACTIVE.get() else (256,8192,512)
+
+def active():return _ACTIVE.get()
+
+@contextmanager
+def large_modal_capacity():
+    if _ACTIVE.get():raise ValueError('nested large modal capacity forbidden')
+    token=_ACTIVE.set(True)
+    try:yield
+    finally:_ACTIVE.reset(token)
+
+def solve_large_factor_chain_modes(*args,**kwargs):
+    from ._native_paired_factor_chain_modes import solve_paired_factor_chain_modes
+    with large_modal_capacity():return solve_paired_factor_chain_modes(*args,**kwargs)
+
+def apply_large_mode_map(*args,**kwargs):
+    from ._native_paired_factor_chain_modes import apply_mode_map
+    with large_modal_capacity():return apply_mode_map(*args,**kwargs)

anyfesolver/_native_paired_factor_chain_modes.py

@@ -0,0 +1,244 @@
+"""Private paired-vector successor of the preserved relative factor kernel.
+
+The preserved factor reduction is a preconditioner, not eigenvalue authority.
+Reassemble the ORIGINAL signed bilinear form and kinetic Gram matrix in its
+complete dynamic map, then bracket the generalized pencil. No truncated Ritz
+subspace, clipping, mass floor, mechanics, state transaction or qualification.
+"""
+from dataclasses import dataclass, fields, replace
+from hashlib import sha256
+import json
+from ._paired_modal_arithmetic import orthogonal_coordinates, paired_expansion, paired_actions, paired_map
+from math import fsum, isfinite
+import math
+from fractions import Fraction
+_fma = getattr(math, 'fma', None)
+from time import monotonic
+import numpy as np
+from scipy import linalg
+from anyfesolver._native_signed_kinetic_factor_modes import _reduce, _orthonormalize
+from anyfesolver._native_reference_modal import _owned
+from anyfesolver.control import cancellation_safe_point
+from anyfesolver._dyadic_factor_chain import reassemble_chain_exact_binary64
+
+
+def product_error(x, y, product):
+    # Python <3.13 portability without changing package requirements. Exact
+    # rational reconstruction rounds the same residual as fused multiply-add.
+    # This is an arithmetic backend, never a mechanical/legacy fallback.
+    if _fma is not None:
+        return _fma(x, y, -product)
+    return float(Fraction(x)*Fraction(y)-Fraction(product))
+
+
+def dot_terms(a,b):
+    terms=[]
+    for x,y in zip(a,b):
+        x,y=float(x),float(y); product=x*y
+        if not isfinite(product): raise ValueError('nonfinite compensated product')
+        if product==0. and x!=0. and y!=0.: raise ValueError('underflowed compensated product')
+        terms.extend((product,product_error(x,y,product)))
+    return terms
+
+
+def mm(a,b,checkpoint=lambda:None):
+    if a.ndim!=2 or b.ndim!=2 or a.shape[1]!=b.shape[0]: raise ValueError('matching matrix dimensions')
+    from ._native_modal_capacity import active
+    if active() and np.count_nonzero(a)*2<a.size:
+        from ._native_large_factor_chain import sparse_float_product
+        return sparse_float_product(a,b,dot_terms,checkpoint)
+    rows=[]
+    for row in a:
+        checkpoint(); rows.append([fsum(dot_terms(row,col)) for col in b.T])
+    return np.array(rows)
+
+
+def reassemble(left,right,g,b,mapping,checkpoint=lambda:None):
+    return reassemble_chain_exact_binary64(left,right,g,b,mapping,checkpoint)
+
+
+def shifted(h,mass,shift):
+    n=len(h)
+    a=np.array([[fsum([float(h[i,j]), *dot_terms([-shift],[mass[i,j]])])
+        for j in range(n)] for i in range(n)])
+    size=np.abs(np.diag(a)); size=np.where(size==0.,np.max(np.abs(a),axis=1),size)
+    scale=np.sqrt(size)
+    if np.any(scale==0.): raise ValueError('unresolved shifted sign')
+    return a/scale[:,None]/scale[None,:],scale
+
+
+def inertia(h,mass,shift):
+    a,_=shifted(h,mass,shift); values=linalg.eigvalsh(a)
+    margin=64*np.finfo(float).eps*len(h)*max(1.,np.max(np.abs(values)))
+    if np.min(np.abs(values))<=margin: raise ValueError('unresolved shifted sign')
+    return int(np.count_nonzero(values<0.))
+
+
+def brackets(h,mass,bounds,count,absolute,relative,checkpoint):
+    if inertia(h,mass,bounds[0])!=0 or inertia(h,mass,bounds[1])<count:
+        raise ValueError('bounds do not enclose lowest requested roots')
+    results=[];widths=[]
+    for index in range(count):
+        lo,hi=bounds
+        for _ in range(192):
+            checkpoint()
+            mid=lo+(hi-lo)/2
+            width=absolute+relative*abs(mid)
+            if hi-lo<=width:break
+            try:negative=inertia(h,mass,mid)
+            except ValueError as exc:
+                if str(exc)!='unresolved shifted sign':raise
+                left,right=max(lo,mid-width/4),min(hi,mid+width/4)
+                a,b=inertia(h,mass,left),inertia(h,mass,right)
+                if a>b:raise ValueError('nonmonotone relative shifted inertia')
+                if a<=index<b:
+                    lo,hi=left,right;break
+                if index<a:
+                    hi=left;continue
+                if b<=index:
+                    lo=right;continue
+                raise ValueError('relative shifted signs unresolved') from exc
+            if negative<=index:lo=mid
+            else:hi=mid
+        else:raise ValueError('relative signed search iteration limit')
+        width=absolute+relative*abs(lo+(hi-lo)/2)
+        if hi-lo>width:raise ValueError('relative signed search width not achieved')
+        results.append((lo,hi));widths.append(width)
+    return np.array(results),np.array(widths)
+
+
+@dataclass(frozen=True)
+class PairedFactorChainModes:
+    eigenvalues: np.ndarray
+    high_modes: np.ndarray
+    low_modes: np.ndarray
+    numerical_brackets: np.ndarray
+    spectral_residual: float
+    full_backward_residual: float
+    original_ritz_residual: float
+    policy: str='PRIVATE_COMPLETE_MAP_PAIRED_FACTOR_CHAIN_SIGNED_MODES_V1'
+    bracket_absolute_width: float=1e-10
+    bracket_relative_width: float=1e-12
+    bilinear_arithmetic: str='EXACT_DYADIC_FACTOR_CHAIN_CONGRUENCE_ROUNDED_ONCE'
+    negative_eigenvalues_retained: bool=True
+    certified_intervals: bool=False
+    production_qualified: bool=False
+    fingerprint: str=''
+
+    @property
+    def full_modes(self):
+        raise AttributeError('paired modes require explicit high/low action; no validated high-only array')
+
+
+def _fingerprint(result):
+    payload={f.name:getattr(result,f.name) for f in fields(result) if f.name!='fingerprint'}
+    return sha256(json.dumps(payload,sort_keys=True,separators=(',',':'),allow_nan=False,
+        default=lambda a:a.tolist()).encode()).hexdigest()
+
+
+def validate_modes(result):
+    if type(result) is not PairedFactorChainModes or _fingerprint(result)!=result.fingerprint:
+        raise ValueError('paired modal result identity changed')
+    if (result.high_modes.shape!=result.low_modes.shape or result.high_modes.shape[1]!=len(result.eigenvalues)
+            or any(a.flags.writeable for a in (result.high_modes,result.low_modes,result.eigenvalues,result.numerical_brackets))):
+        raise ValueError('owned matching immutable paired modal arrays required')
+    return result
+
+
+def apply_mode_map(result,operator,checkpoint=lambda:None):
+    validate_modes(result)
+    output=paired_map(operator,result.high_modes,result.low_modes,checkpoint)
+    validate_modes(result)
+    return _owned(output)
+
+
+def solve_paired_factor_chain_modes(left_factor,right_factor,geometric,kinetic,free,algebraic,*,bounds,num_modes=6,root_width=1e-10,relative_width=1e-12,cancellation_token=None):
+    from ._native_modal_capacity import limits
+    coordinates,rows,links=limits()
+    start=monotonic()
+    def checkpoint(stage='reassembly'):
+        cancellation_safe_point(cancellation_token,'compensated_spectrum.'+stage)
+        if monotonic()-start>600.: raise ValueError('compensated spectrum deadline')
+    checkpoint('capture')
+    left,right,g,b=(_owned(x) for x in (left_factor,right_factor,geometric,kinetic))
+    if (left.ndim!=2 or right.ndim!=2 or not 1<=left.shape[0]<=rows
+            or not 1<=right.shape[0]<=links or not 1<=right.shape[1]<=coordinates
+            or left.shape[1]!=right.shape[0]):
+        raise ValueError('bounded matching owned factor chain')
+    # Rounded expansion is only a preconditioner for a complete dynamic map.
+    # The signed pencil and returned-vector audit use the original chain.
+    f=mm(left,right,checkpoint)
+    if (b.ndim!=2 or f.ndim!=2 or not 1<=b.shape[0]<=rows or not 1<=b.shape[1]<=coordinates
+            or f.shape[1]!=b.shape[1]): raise ValueError('bounded matching factors')
+    if (type(bounds) is not tuple or len(bounds)!=2 or any(type(v) not in (float,int) or not isfinite(v) for v in bounds)
+            or bounds[0]>=bounds[1] or type(num_modes) is not int or num_modes<1
+            or type(root_width) is not float or not isfinite(root_width) or root_width<=0.
+            or type(relative_width) is not float or not isfinite(relative_width) or not 0<relative_width<=1e-10):
+        raise ValueError('explicit finite root controls required')
+    dense_mass=b.T@b
+    _,_,mapping=_reduce(f,g,dense_mass,free,algebraic,checkpoint,b)
+    h,mass=reassemble(left,right,g,b,mapping,checkpoint)
+    if num_modes>len(h): raise ValueError('mode count exceeds dynamic coordinates')
+    linalg.cholesky(mass)
+    intervals,widths=brackets(h,mass,bounds,num_modes,root_width,relative_width,checkpoint)
+    coordinates=[]; values=[]; index=0
+    while index<num_modes:
+        end=index+1
+        while end<num_modes and intervals[end,0]-intervals[end-1,1]<=8*max(widths[end],widths[end-1]): end+=1
+        if inertia(h,mass,intervals[index,0])!=index or inertia(h,mass,intervals[end-1,1])!=end:
+            raise ValueError('requested modes truncate a cluster')
+        cluster_width=float(np.max(widths[index:end]))
+        shifted_matrix,scale=shifted(h,mass,float(intervals[index,0]-2*cluster_width))
+        roots,vectors=linalg.eigh(shifted_matrix); raw=vectors/scale[:,None]
+        scores=np.abs(roots)/np.einsum('ij,ij->j',raw,mass@raw)
+        basis=_orthonormalize(raw[:,np.argsort(scores,kind='stable')[:end-index]])
+        lu=linalg.lu_factor(shifted_matrix)
+        for _ in range(2):
+            checkpoint('inverse')
+            basis=_orthonormalize(linalg.lu_solve(lu,mm(mass,basis,checkpoint)/scale[:,None])/scale[:,None])
+        # Complete-map pencil, not the earlier approximate material singular values.
+        small_h=mm(basis.T,mm(h,basis,checkpoint),checkpoint); small_m=mm(basis.T,mm(mass,basis,checkpoint),checkpoint)
+        rv,ru=linalg.eigh(small_h,small_m); actual=mm(basis,ru,checkpoint)
+        if np.any(rv<intervals[index:end,0]-widths[index:end]) or np.any(rv>intervals[index:end,1]+widths[index:end]):
+            raise ValueError('reassembled Ritz roots leave numerical brackets')
+        coordinates.append(actual); values.extend(rv); index=end
+    c=orthogonal_coordinates(np.column_stack(coordinates),mass,checkpoint); values=np.array(values)
+    hc=mm(h,c,checkpoint); mc=mm(mass,c,checkpoint)
+    residual=hc-mc*values
+    # Preserve the separate material/geometric ACTION scale. Scaling by the
+    # already cancelled tangent action asks for absolute force accuracy when
+    # large material and prestress forces balance. Never use the norm of an
+    # unrelated stiff direction as the denominator.
+    strain=mm(left,mm(right,mapping,checkpoint),checkpoint); material_action=mm(strain.T,mm(strain,c,checkpoint),checkpoint)
+    geometric_action=mm(mapping.T,mm(g,mm(mapping,c,checkpoint),checkpoint),checkpoint)
+    scale=np.maximum(1.,np.maximum(np.linalg.norm(material_action,axis=0),
+        np.maximum(np.linalg.norm(geometric_action,axis=0),np.linalg.norm(mc*values,axis=0))))
+    if not np.isfinite(scale).all(): raise ValueError('nonfinite reassembled action scale')
+    error=float(np.max(np.linalg.norm(residual,axis=0)/scale))
+    if not isfinite(error) or error>1e-11: raise ValueError('reassembled action residual')
+    high,low=paired_expansion(mapping,c,checkpoint)
+    original_h,original_m,full_action,material_full,geometric_full,inertia_full=paired_actions(
+        left,right,g,b,high,low,values,checkpoint)
+    if np.linalg.norm(original_m-np.eye(num_modes))>1e-11:
+        raise ValueError('physical modal mass normalization')
+    # Audit the ORIGINAL signed form using both physical vector halves.
+    ritz_difference=original_h-original_m*values[None,:]
+    ritz_scale=np.maximum(1.,np.sqrt(np.abs(values))[:,None]*np.sqrt(np.abs(values))[None,:])
+    original_error=float(np.max(np.abs(ritz_difference)/ritz_scale))
+    if not isfinite(original_error) or original_error>1e-11:
+        raise ValueError('original signed bilinear Ritz identity failed')
+    for j in range(num_modes):
+        if high[int(np.argmax(np.abs(high[:,j]))),j]<0.:
+            high[:,j]*=-1.;low[:,j]*=-1.
+    # Same normwise full backward threshold as the preserved kernel, now
+    # with exact original-chain actions rather than an expanded Gram product.
+    scale=max(1.,(np.linalg.norm(f)**2+np.linalg.norm(g))*np.linalg.norm(high),
+        np.linalg.norm(dense_mass)*np.linalg.norm(high*values))
+    if not isfinite(scale): raise ValueError('nonfinite full backward scale')
+    backward=float(np.linalg.norm(full_action[list(free)])/scale)
+    if not isfinite(backward) or backward>1e-11: raise ValueError('full backward residual')
+    checkpoint('output')
+    result=PairedFactorChainModes(_owned(values),_owned(high),_owned(low),_owned(intervals),
+        error,backward,original_error,bracket_absolute_width=root_width,bracket_relative_width=relative_width)
+    result=replace(result,fingerprint=_fingerprint(result))
+    return validate_modes(result)