sawsim 2.0.1__py3-none-any.whl

sawsim/__init__.py

@@ -0,0 +1,9 @@
+"""SawSim: piezoelectric coupled FEM for SAW resonator unit cells."""
+__version__ = "2.0.1"
+
+from sawsim import runtime as _runtime  # noqa: F401,E402  (GL shims before gmsh is imported anywhere)
+
+from sawsim.config import SimulationConfig  # noqa: E402
+from sawsim.api import Model, sweep, Result  # noqa: E402
+
+__all__ = ["SimulationConfig", "Model", "sweep", "Result", "__version__"]

sawsim/api.py

@@ -0,0 +1,90 @@
+"""Public Python API: Model -> sweep -> Result."""
+from __future__ import annotations
+import json, shutil, tempfile
+from pathlib import Path
+from typing import Callable, Optional
+import numpy as np
+
+from sawsim.config import SimulationConfig
+from sawsim.sp_specs import MODEL_SPECS
+
+
+class Model:
+    """A unit-cell model: template id plus any SimulationConfig fields.
+
+    >>> m = Model("sp_double_layer", pitch_um=1.085, points=101)
+    """
+    def __init__(self, model_id: str = "sp_single_layer", **params):
+        self.config = SimulationConfig.model_validate(dict(params, model_id=model_id))
+
+    @classmethod
+    def from_json(cls, path) -> "Model":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(**data)
+
+    @staticmethod
+    def templates() -> dict:
+        return {k: v["name"] for k, v in MODEL_SPECS.items()}
+
+    def to_dict(self) -> dict:
+        return self.config.model_dump()
+
+    def __repr__(self):
+        c = self.config
+        return f"Model({c.model_id!r}, pitch_um={c.pitch_um}, points={c.points}, {c.start_ghz}-{c.stop_ghz} GHz)"
+
+
+class Result:
+    """Results of one sweep, backed by an output directory (curve.json, metadata.json, images, npz)."""
+    def __init__(self, output_dir):
+        self.dir = Path(output_dir)
+        self.manifest = self._load("manifest.json")
+        self.metadata = self._load("metadata.json")
+        self.curve = self._load("curve.json")
+
+    def _load(self, name):
+        p = self.dir / name
+        return json.loads(p.read_text(encoding="utf-8")) if p.exists() else {}
+
+    @property
+    def frequency_ghz(self) -> np.ndarray:
+        return np.asarray(self.curve.get("frequency_ghz", []), dtype=float)
+
+    @property
+    def admittance(self) -> np.ndarray:
+        return np.asarray(self.curve.get("real", []), dtype=float) + 1j * np.asarray(self.curve.get("imag", []), dtype=float)
+
+    @property
+    def magnitude(self) -> np.ndarray:
+        return np.abs(self.admittance)
+
+    @property
+    def peak_frequency_ghz(self) -> Optional[float]:
+        return self.metadata.get("peak_frequency_ghz")
+
+    def artifact(self, name: str) -> Path:
+        return self.dir / name
+
+    def save(self, target) -> Path:
+        """Copy the whole result directory to `target` (created if needed)."""
+        target = Path(target)
+        if target.resolve() != self.dir.resolve():
+            shutil.copytree(self.dir, target, dirs_exist_ok=True)
+        return target
+
+    def __repr__(self):
+        return f"Result({self.dir}, {len(self.frequency_ghz)} points, peak={self.peak_frequency_ghz} GHz)"
+
+
+def sweep(model: Model | SimulationConfig | dict, output_dir=None, *, mesh_only: bool = False,
+          on_progress: Optional[Callable] = None) -> Result:
+    """Run the frequency sweep (or only build the mesh) and return a Result.
+
+    If output_dir is None a fresh temporary directory is used.
+    """
+    from sawsim.solver import run_simulation
+    cfg = model.config if isinstance(model, Model) else model
+    out = Path(output_dir) if output_dir else Path(tempfile.mkdtemp(prefix="sawsim_"))
+    out.mkdir(parents=True, exist_ok=True)
+    run_simulation(cfg, str(out), on_progress=on_progress, mesh_only=mesh_only)
+    return Result(out)

sawsim/cli.py

@@ -0,0 +1,48 @@
+"""Command-line interface: sawsim run | templates | serve."""
+import argparse, json, sys
+from pathlib import Path
+
+
+def cmd_run(args):
+    from sawsim.api import Model, sweep
+    data = json.loads(Path(args.config).read_text(encoding="utf-8"))
+    model = Model(**data)
+    def progress(ev):
+        if args.quiet: return
+        print(f"\r{ev.get('stage','')} {ev.get('completed',0)}/{ev.get('total',0)}  {ev.get('elapsed_seconds',0):.1f}s", end="", file=sys.stderr, flush=True)
+    res = sweep(model, args.output, mesh_only=args.mesh_only, on_progress=progress)
+    if not args.quiet: print(file=sys.stderr)
+    print(f"output: {res.dir}")
+    if not args.mesh_only:
+        print(f"points: {len(res.frequency_ghz)}  peak: {res.peak_frequency_ghz} GHz  |Y|max: {res.magnitude.max():.4g}")
+    return 0
+
+
+def cmd_templates(args):
+    from sawsim.api import Model
+    for k, v in Model.templates().items():
+        print(f"{k:24s} {v}")
+    return 0
+
+
+def cmd_serve(args):
+    print("`sawsim serve` (local web UI) ships with the web extra in a later step; run the API with:\n"
+          "  python -m uvicorn sawsim_web.app:app --port 8765", file=sys.stderr)
+    return 2
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="sawsim", description="SawSim unit-cell piezoelectric FEM")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run", help="run a sweep from a JSON config")
+    r.add_argument("config"); r.add_argument("-o", "--output", required=True)
+    r.add_argument("--mesh-only", action="store_true"); r.add_argument("-q", "--quiet", action="store_true")
+    r.set_defaults(fn=cmd_run)
+    t = sub.add_parser("templates", help="list model templates"); t.set_defaults(fn=cmd_templates)
+    s = sub.add_parser("serve", help="start the local web UI"); s.set_defaults(fn=cmd_serve)
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sawsim/config.py

@@ -0,0 +1,150 @@
+"""Validated SP family inputs; lengths in µm, frequency in GHz, angles in degrees."""
+from copy import deepcopy
+from typing import Literal, Optional, List, Dict
+from pydantic import BaseModel, Field, model_validator, ConfigDict
+
+
+class LayerConfig(BaseModel):
+    model_config = ConfigDict(extra='forbid', allow_inf_nan=False)
+    material_id: str
+    thickness_um: float = Field(gt=0, le=30)
+    euler_phi_deg: float = Field(0.0, ge=-360, le=360)
+    euler_theta_deg: float = Field(0.0, ge=-360, le=360)
+    euler_psi_deg: float = Field(0.0, ge=-360, le=360)
+
+
+class SimulationConfig(BaseModel):
+    model_config = ConfigDict(extra='forbid', allow_inf_nan=False)
+    model_id: str = 'sp_single_layer'
+    mode_extension: int = Field(1, ge=0, le=1, strict=True)
+    substrate_material: str = 'sp_baseline'
+    electrode_material: str = 'al'
+    layers: List[LayerConfig] = Field(default_factory=list)
+    material_snapshots: Dict[str, dict] = Field(default_factory=dict, max_length=12)
+    # phi/theta/psi are intrinsic ZXZ alpha/beta/gamma, in degrees. Convention id 'zxz'; legacy ids accepted as aliases.
+    euler_convention: Literal['zxz'] = 'zxz'
+    euler_phi_deg: float = Field(0.0, ge=-360, le=360)
+    euler_theta_deg: float = Field(-42.0, ge=-360, le=360)
+    euler_psi_deg: float = Field(0.0, ge=-360, le=360)
+    aperture_um: Optional[float] = Field(None, gt=0)
+    pitch_um: float = Field(1.085, gt=0)
+    electrode_um: float = Field(0.17, gt=0)
+    substrate_um: float = Field(8, gt=0)
+    metal_ratio: float = Field(0.5, gt=0, lt=1)
+    mesh_um: float = Field(0.5, gt=0)
+    start_ghz: float = Field(1.5, gt=0)
+    stop_ghz: float = Field(2.7, gt=0)
+    points: int = Field(41, ge=3, le=1201, strict=True)
+    voltage: float = Field(1.0, gt=0)
+
+    @model_validator(mode='before')
+    @classmethod
+    def model_defaults(cls, data):
+        if not isinstance(data, dict):
+            return data
+        from sawsim.sp_specs import MODEL_SPECS
+        model_id = data.get('model_id','sp_single_layer')
+        if not isinstance(model_id,str) or model_id not in MODEL_SPECS:
+            raise ValueError('未知模型: ' + str(model_id))
+        defaults = deepcopy(MODEL_SPECS[model_id]['defaults'])
+        if data.get('euler_convention') in ('reference_zxz', 'zxz_intrinsic'):
+            data = dict(data, euler_convention='zxz')
+        if data.get('euler_convention') == 'legacy_zxz':
+            keys = ('euler_phi_deg', 'euler_theta_deg', 'euler_psi_deg')
+            old_defaults = dict(zip(keys, [-defaults[k] for k in reversed(keys)]))
+            try:
+                angles = [float(data.get(k, old_defaults[k])) for k in keys]
+            except (TypeError, ValueError):
+                raise ValueError('旧欧拉角必须为有限数值，单位度')
+            data = dict(data, **dict(zip(keys, [-v for v in reversed(angles)])))
+            data['euler_convention'] = 'zxz'
+        return dict(defaults, **data)
+
+    @model_validator(mode='after')
+    def validate_model(self):
+        from sawsim.sp_specs import MODEL_SPECS
+        from sawsim.material_library import get_record
+        from sawsim.material_library.schema import MaterialRecord
+        references=[(self.substrate_material,'substrate'),(self.electrode_material,'electrode')]
+        references += [(layer.material_id,'layer') for layer in self.layers]
+        used={mid for mid,role in references}
+        if set(self.material_snapshots)-used:
+            raise ValueError('材料快照包含未使用的材料 ID')
+        snapshots={}
+        for mid,role in references:
+            try:
+                record=MaterialRecord.model_validate(self.material_snapshots[mid] if mid in self.material_snapshots else get_record(mid)).model_dump()
+            except KeyError:
+                raise ValueError('未知材料: '+mid)
+            if record['id']!=mid or role not in record['roles']:
+                raise ValueError('材料 ID 或适用区域不匹配: '+mid)
+            snapshots[mid]=record
+        self.material_snapshots=snapshots
+        spec=MODEL_SPECS[self.model_id]
+        if self.model_id.startswith('sp_2p5d_'):
+            if self.aperture_um is None:
+                raise ValueError('2.5D 薄片模型需要 aperture_um')
+        elif self.aperture_um is not None:
+            raise ValueError('aperture_um 仅适用于 2.5D Hex27 薄片模型')
+        if self.mode_extension not in spec['supported_mode_extensions']:
+            raise ValueError('该模型不支持所选 ME 模式')
+        if len(self.layers)!=spec['layer_count']:
+            raise ValueError('该模型需要 %d 个附加层' % spec['layer_count'])
+        for layer in self.layers:
+            lower=spec.get('layer_thickness_min_um',0.01)
+            upper=spec.get('layer_thickness_max_um',20.0)
+            if not lower<=layer.thickness_um<=upper:
+                raise ValueError('附加层厚度超出允许范围 [%s,%s] µm' % (lower,upper))
+        for field in spec['numeric_fields']:
+            value=getattr(self,field['key'])
+            if not field['min']<=value<=field['max']:
+                raise ValueError('%s 超出允许范围 [%s,%s]' % (field['key'],field['min'],field['max']))
+        if self.model_id=='sp_tcsaw' and self.layers[0].thickness_um<=self.electrode_um:
+            raise ValueError('TC 内侧包覆层厚度必须大于电极厚度')
+        if self.stop_ghz<=self.start_ghz:
+            raise ValueError('结束频率必须大于起始频率')
+        return self
+
+
+def config_from_saved(data):
+    """Import saved tasks: pre-0.6 inputs without a marker use legacy ZXZ.
+
+    New unmarked API/CLI inputs use the current ZXZ convention; use this only for historical imports.
+    """
+    cfg=SimulationConfig.model_validate(dict(
+        data, euler_convention=data.get('euler_convention', 'legacy_zxz')))
+    if not data.get('material_snapshots'):
+        # Pre-library tasks used the initial immutable historical datasets.
+        from sawsim.material_library import get_record
+        for mid,record in list(cfg.material_snapshots.items()):
+            if record['status']=='legacy':
+                cfg.material_snapshots[mid]=get_record(mid,'1.0.0')
+    return cfg
+
+
+Config=SimulationConfig
+
+
+class ProgressEvent(BaseModel):
+    stage: str
+    stage_id: str
+    completed: int = Field(ge=0)
+    total: int = Field(ge=1)
+    elapsed_seconds: float = Field(ge=0)
+    frequency_hz: Optional[float] = None
+
+
+class Artifact(BaseModel):
+    name: str
+    kind: str
+    media_type: str
+
+
+class ResultManifest(BaseModel):
+    schema_version: Literal['1.0'] = '1.0'
+    model_id: str
+    artifacts: List[Artifact]
+
+
+from sawsim.models import list_models
+MODEL_TEMPLATES=list_models()

sawsim/frequency_tasks.py

@@ -0,0 +1,55 @@
+"""Bounded, ordered frequency solves; existing FEM engines remain unchanged."""
+from contextlib import contextmanager
+import multiprocessing as mp
+import os
+import numpy as np
+
+_engine = None
+_voltage = None
+_hex = False
+
+
+def worker_count(points):
+    configured = os.environ.get('SAW_SWEEP_WORKERS')
+    workers = int(configured) if configured is not None else (8 if points > 41 else 1)
+    if not 1 <= workers <= 8:
+        raise ValueError('SAW_SWEEP_WORKERS must be an integer from 1 to 8')
+    if 'fork' not in mp.get_all_start_methods():
+        return 1
+    return min(workers, points, os.cpu_count() or 1)
+
+
+def _initialize(engine, voltage, is_hex):
+    global _engine, _voltage, _hex
+    _engine, _voltage, _hex = engine, voltage, is_hex
+
+
+def _charge(frequency):
+    kwargs = {'voltage': _voltage} if _hex else {'V': _voltage}
+    return complex(_engine.solve(2*np.pi*frequency, **kwargs)[1])
+
+
+@contextmanager
+def charge_stream(engine, frequencies, voltage, *, is_hex=False):
+    """Yield charges in frequency order; clean up workers on failure/cancellation.
+
+    Fork workers inherit the already assembled read-only matrices. Each engine's
+    existing backend handles its process-local factorization. Only scalar
+    charges return to the parent; full fields are solved once at the peak.
+    """
+    count = worker_count(len(frequencies))
+    if count == 1:
+        kwargs = {'voltage': voltage} if is_hex else {'V': voltage}
+        yield (complex(engine.solve(2*np.pi*f, **kwargs)[1]) for f in frequencies)
+        return
+    pool = mp.get_context('fork').Pool(count, initializer=_initialize,
+                                       initargs=(engine, voltage, is_hex))
+    try:
+        yield pool.imap(_charge, frequencies, chunksize=1)
+    except BaseException:
+        pool.terminate()
+        raise
+    else:
+        pool.close()
+    finally:
+        pool.join()

sawsim/hex_models.py

@@ -0,0 +1,94 @@
+"""Original Hex27 periodic thin-slice builders, adapted to project configurations."""
+from dataclasses import dataclass
+import numpy as np
+from sawsim import runtime
+import gmsh
+from sawsim.saw2d import materials
+from sawsim.saw2d.saw3d import harvest_3d_mesh,find_saw_boundary_3ds,boundary_idx_vect_3ds
+from sawsim.sp_hex_meshes import build_mesh
+
+
+@dataclass
+class HexModel:
+    mesh: object
+    position_m: np.ndarray
+    material_type: list
+    pml: list
+    boundary: object
+    material_data: dict
+    details: dict
+    preview_quads: np.ndarray
+    preview_tags: np.ndarray
+
+
+def _front_faces(mesh,position):
+    y0=float(position[:,1].min())
+    on_front=np.isclose(position[:,1],y0,rtol=0,atol=1e-14)
+    owners={}
+    for hexa,tag in zip(mesh.hexas27,mesh.hex_tag):
+        nodes=hexa[on_front[hexa]]
+        if len(nodes)==9:owners[frozenset(nodes.tolist())]=int(tag)
+    faces=[];tags=[];seen=set()
+    for face in mesh.quads9:
+        key=frozenset(face.tolist())
+        if key in owners and key not in seen:
+            faces.append(face);tags.append(owners[key]);seen.add(key)
+    if len(faces)!=len(owners) or not faces:raise ValueError('Cannot recover complete y=0 front section from Hex27 mesh')
+    return np.array(faces,dtype=int),np.array(tags,dtype=int)
+
+
+def _check_pair(sets,position,a,b,axis,span):
+    left=sets[a];right=sets[b];other=[i for i in range(3) if i!=axis]
+    def ordered(nodes):
+        coordinates=np.round(position[nodes][:,other],14)
+        return nodes[np.lexsort((coordinates[:,1],coordinates[:,0]))]
+    left=ordered(left);right=ordered(right)
+    if len(left)!=len(right) or not np.allclose(position[left][:,other],position[right][:,other],rtol=0,atol=1e-13):
+        raise ValueError('Hex27 periodic boundary coordinates do not match: '+a+'/'+b)
+    if not np.allclose(np.abs(position[right,axis]-position[left,axis]),span,rtol=0,atol=1e-13):
+        raise ValueError('Hex27 periodic span does not match geometry: '+a+'/'+b)
+
+
+def build_hex_model(config):
+    try:
+        info=build_mesh(config)
+        if set(int(t) for t in gmsh.model.mesh.getElementTypes(3))!={12}:
+            raise ValueError('2.5D thin-slice model requires only Hex27 volume elements')
+        mesh=harvest_3d_mesh()
+    finally:
+        if gmsh.isInitialized():gmsh.finalize()
+    position=mesh.pos*1e-6
+    sets=find_saw_boundary_3ds(mesh)
+    _check_pair(sets,position,'L','R',0,info['period_m'])
+    _check_pair(sets,position,'front','back',1,info['aperture_m'])
+    bottom=float(position[sets['bottom'],2].min())
+    angles=[config.euler_phi_deg,config.euler_theta_deg,config.euler_psi_deg]
+    from sawsim.material_runtime import resolve_materials
+    chosen,source,library_tensors,provenance=resolve_materials(config)
+    ids=[config.substrate_material,config.electrode_material]+[layer.material_id for layer in config.layers]
+    missing=set(int(t) for t in mesh.hex_tag)-set(info['tag_map'])
+    if missing:raise ValueError('Unmapped Hex27 material tags: '+str(missing))
+    material_type=[dict(rho=chosen[index].rho,C=chosen[index].C,e=chosen[index].e,eps=chosen[index].eps,
+                        indx=np.where(mesh.hex_tag==tag)[0])
+                   for tag,index in info['tag_map'].items() if tag!=info['pml_tag']]
+    pml_index=info['tag_map'][info['pml_tag']];pml_mat=chosen[pml_index]
+    pml=[dict(region=1,indx=np.array([],dtype=np.int64)),dict(region=2,indx=np.array([],dtype=np.int64)),
+         dict(region=3,indx=np.where(mesh.hex_tag==info['pml_tag'])[0],za=bottom+info['pml_thickness_m'],zp=bottom,
+              xa=0.,xp=0.,dmax=1e11,n=3,rho=pml_mat.rho,C=pml_mat.C,e=pml_mat.e,eps=pml_mat.eps)]
+    faces,face_tags=_front_faces(mesh,position)
+    tensor_data=dict(material_ids=ids,rho_kg_m3=[m.rho for m in chosen],
+                     full_C_pa=np.stack([m.C for m in chosen]),full_e_c_m2=np.stack([m.e for m in chosen]),
+                     full_eps_f_m=np.stack([m.eps for m in chosen]),
+                     substrate_source_C_pa=source.C,substrate_source_e_c_m2=source.e,substrate_source_eps_f_m=source.eps,
+                     rotation_matrix=materials.rotation_matrix(angles),euler_angles_deg=angles,
+                     mode_extension=1,coordinate_mapping='source_xyz_to_mesh_xyz',pml_material_id=ids[pml_index])
+    tensor_data.update(library_tensors)
+    details=dict(info,material_library=provenance,material_region_ids={str(tag):ids[index] for tag,index in info['tag_map'].items()},
+                 material_regions={str(tag):ids[index]+(' PML' if tag==info['pml_tag'] else '') for tag,index in info['tag_map'].items()},
+                 pml_bottom_m=bottom,pml_interface_m=bottom+info['pml_thickness_m'],pml_material_id=ids[pml_index],
+                 layers=[layer.model_dump() for layer in config.layers],euler_angles_deg=angles,
+                 substrate_material=config.substrate_material,electrode_material=config.electrode_material,
+                 mesh_view_axes=[0,2],mesh_view_note='真实前截面 y=0，横轴x、纵轴z；不是三维体渲染。',
+                 source_compatibility_notes=['Original Hex27 strain matrix omits du_z/dy in gamma_yz; retained for source regression.',
+                     'Original PML Voigt stretch and two-stage periodic condensation retained; not independently validated as general 3D.'])
+    return HexModel(mesh,position,material_type,pml,boundary_idx_vect_3ds(sets,position,3*mesh.nb_nod),tensor_data,details,faces,face_tags)

sawsim/hex_solver.py

@@ -0,0 +1,125 @@
+"""Bounded Hex27 thin-slice pipeline; original source-compatible operators."""
+import time
+import sys
+import hashlib
+import json
+from pathlib import Path
+import numpy as np
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from matplotlib.collections import PolyCollection
+from sawsim.config import ProgressEvent,ResultManifest
+from sawsim.hex_models import build_hex_model
+from sawsim.saw2d.saw3d import form_stiffness_mass_3d,build_periodic_operators,FrequencySolver3D,KM_SCALE
+from sawsim.saw2d.saw3d.bc_solve import _HAVE_PARDISO
+from sawsim.frequency_tasks import charge_stream, worker_count
+ROOT=Path(__file__).resolve().parent
+MAX_HEX_ELEMENTS=2000
+MAX_HEX_NODES=30000
+
+
+def _front_plot(built,path,title,values=None):
+    polygons=built.position_m[built.preview_quads[:,:4]][:,:,[0,2]]*1e6
+    fig,ax=plt.subplots(figsize=(5,10))
+    if values is None:
+        palette=['#4C72B0','#C44E52','#55A868','#8172B2','#CCB974','#64B5CD']
+        groups={}
+        for tag,label in built.details['material_regions'].items():
+            groups.setdefault(label,[]).append(int(tag))
+        for index,(label,tags) in enumerate(groups.items()):
+            group=np.isin(built.preview_tags,tags)
+            if not group.any():continue
+            collection=PolyCollection(polygons[group],facecolors=palette[index%len(palette)],edgecolors='#172b3b',linewidths=.45,label=label)
+            ax.add_collection(collection)
+        ax.legend(loc='upper center',bbox_to_anchor=(.5,-.08),fontsize=7)
+    else:
+        collection=PolyCollection(polygons,array=np.asarray(values)[built.preview_quads[:,:4]].mean(axis=1),cmap='turbo',edgecolors='face')
+        ax.add_collection(collection);fig.colorbar(collection,ax=ax,shrink=.7)
+    ax.autoscale_view();ax.set_aspect('equal');ax.set_xlabel('x / um');ax.set_ylabel('z / um')
+    ax.set_title(title+'\nFront section y=0 (not volume rendering)',fontsize=9)
+    fig.tight_layout();fig.savefig(path,dpi=130,bbox_inches='tight');plt.close(fig)
+
+
+def run_hex_simulation(cfg,output_dir,on_progress=None,should_cancel=None,*,mesh_only=False):
+    from sawsim.solver import atomic_json,dependency_version,publish_mesh
+    out=Path(output_dir);out.mkdir(parents=True,exist_ok=True)
+    if any((out/name).exists() for name in ['manifest.json','mesh.npz','admittance.npz']):
+        raise FileExistsError('输出目录已有计算结果，请使用新的输出目录')
+    atomic_json(out/'input.json',cfg.model_dump());started=time.time()
+    def check():
+        if (out/'cancel').exists() or (should_cancel is not None and should_cancel()):raise InterruptedError('任务已取消')
+    def progress(stage,done=0,stage_id='mesh',frequency_hz=None):
+        check()
+        event=ProgressEvent(stage=stage,stage_id=stage_id,completed=done,total=1 if mesh_only else cfg.points,
+                            elapsed_seconds=round(time.time()-started,2),frequency_hz=frequency_hz).model_dump()
+        atomic_json(out/'progress.json',event)
+        if on_progress is not None:on_progress(event)
+        check()
+    progress('生成 2.5D Hex27 薄片网格')
+    built=build_hex_model(cfg);check();mesh=built.mesh;n=mesh.nb_nod;ne=len(mesh.hexas27)
+    publish_mesh(out,built.details,position_m=built.position_m,hexas27=mesh.hexas27,material_tags=mesh.hex_tag,
+                        quads=built.preview_quads,preview_material_tags=built.preview_tags,mesh_view_axes=[0,2])
+    np.savez_compressed(out/'material_data.npz',**built.material_data)
+    _front_plot(built,out/'mesh.png',cfg.model_id+' mesh')
+    from sawsim.material_runtime import snapshot_manifest
+    atomic_json(out/'material_snapshot.json',snapshot_manifest(cfg))
+    aperture=built.details['aperture_m']
+    meta=dict(model_id=cfg.model_id,model='2.5D periodic thin slice / Hex27',mesh_dimension=3,displacement_components=3,
+              component_labels=['ux','uy','uz'],mode_extension=1,kinematics='2.5D periodic thin slice',
+              aperture_m=aperture,aperture_um=aperture*1e6,nodes=int(n),elements=int(ne),dofs=int(4*n),
+              geometry=built.details,mesh_view_axes=[0,2],mesh_view_note=built.details['mesh_view_note'],
+              substrate_material=cfg.substrate_material,electrode_material=cfg.electrode_material,
+              euler_angles_deg=[cfg.euler_phi_deg,cfg.euler_theta_deg,cfg.euler_psi_deg],euler_convention=cfg.euler_convention,euler_angle_labels=['alpha','beta','gamma'],euler_rotation='Rz(alpha) Rx(beta) Rz(gamma)',
+              backend='PARDISO' if _HAVE_PARDISO else 'SciPy SuperLU',solver_version='0.7.0',
+              units={'frequency':'Hz','position':'m','displacement':'m','potential':'V','charge':'C/m reaction',
+                     'admittance':'S/m','raw_charge_c':'C reaction','raw_admittance_s':'S','aperture_m':'m'},
+              normalization='charge=raw_charge_c/aperture_m; admittance=raw_admittance_s/aperture_m; curve uses S/m',
+              sign_convention='Source-compatible potential-equation reaction Q; Y=+i*omega*Q/V. For exp(+iwt), this is outward-current admittance, opposite to standard entering-port Y. Magnitude unchanged.',
+              source_compatibility_notes=built.details['source_compatibility_notes'],
+              resource_limits={'max_hex_elements':MAX_HEX_ELEMENTS,'max_hex_nodes':MAX_HEX_NODES,'numerical_threads':1},
+              python=sys.version,versions={name:dependency_version(name) for name in ['numpy','scipy','gmsh','matplotlib']})
+    files=[ROOT/'frequency_tasks.py',ROOT/'hex_solver.py',ROOT/'hex_models.py',ROOT/'solver.py',ROOT/'models.py',ROOT/'config.py',ROOT/'material_runtime.py',*sorted((ROOT/'material_library').glob('*.py')),ROOT/'sp_specs.py',ROOT/'saw2d/materials.py',
+           *sorted((ROOT/'sp_hex_meshes').glob('*.py')),*sorted((ROOT/'saw2d/saw3d').glob('*.py'))]
+    meta['source_hashes']={str(path.relative_to(ROOT)):hashlib.sha256(path.read_bytes()).hexdigest() for path in files}
+    if not mesh_only:
+        if ne>MAX_HEX_ELEMENTS or n>MAX_HEX_NODES:
+            raise ValueError('Hex27 模型超过本机安全组装上限（2000单元/30000节点），请增大 mesh_um 或减小模型尺寸；已保留真实网格。')
+        progress('组装 Hex27 矩阵',stage_id='assembly')
+        frequencies=np.linspace(cfg.start_ghz*1e9,cfg.stop_ghz*1e9,cfg.points)
+        mass,stiffness=form_stiffness_mass_3d(mesh.hexas27,built.position_m,built.material_type,built.pml,omega=2*np.pi*frequencies[-1])
+        check();tfb,tlr=build_periodic_operators(built.boundary,4*n)
+        engine=FrequencySolver3D(stiffness,mass,built.boundary,tfb,tlr);meta['active_dofs']=int(engine.n_act);meta.update(frequency_count=cfg.points,frequency_workers=worker_count(cfg.points),pml_reference_frequency_hz=float(frequencies[-1]))
+        raw_q=[]
+        with charge_stream(engine,frequencies,cfg.voltage,is_hex=True) as results:
+            for i,f in enumerate(frequencies):
+                progress('真实 Hex27 扫频',i,'sweep',float(f))
+                q=next(results)
+                if not np.isfinite(q):raise ValueError('Hex27 求解产生非有限电荷')
+                raw_q.append(complex(q));y=1j*2*np.pi*frequencies[:i+1]*np.array(raw_q)/(cfg.voltage*aperture)
+                atomic_json(out/'curve.json',dict(frequency_ghz=(frequencies[:i+1]*1e-9).tolist(),real=y.real.tolist(),imag=y.imag.tolist(),magnitude=np.abs(y).tolist()))
+                progress('真实 Hex27 扫频',i+1,'sweep',float(f))
+        progress('生成真实前截面场图',cfg.points,'postprocess')
+        raw_q=np.array(raw_q);raw_y=1j*2*np.pi*frequencies*raw_q/cfg.voltage;y=raw_y/aperture
+        np.savez_compressed(out/'admittance.npz',frequency_hz=frequencies,charge=raw_q/aperture,admittance=y,
+                            raw_charge_c=raw_q,raw_admittance_s=raw_y,aperture_m=aperture)
+        np.savetxt(out/'admittance.csv',np.column_stack([frequencies,y.real,y.imag,np.abs(y),raw_y.real,raw_y.imag,raw_q.real,raw_q.imag]),delimiter=',',
+                   header='frequency_hz,real_y_s_per_m,imag_y_s_per_m,abs_y_s_per_m,raw_real_y_s,raw_imag_y_s,raw_real_reaction_q_c,raw_imag_reaction_q_c',comments='')
+        peak=int(np.argmax(np.abs(y)));state,_,_=engine.solve(2*np.pi*frequencies[peak],voltage=cfg.voltage)
+        if not np.isfinite(state).all():raise ValueError('Hex27 场结果包含非有限值')
+        displacement=state[:3*n].reshape(n,3)*KM_SCALE;potential=state[3*n:]
+        np.savez_compressed(out/'fields.npz',position_m=built.position_m,displacement_m=displacement,potential_v=potential,
+                            frequency_hz=frequencies[peak],hexas27=mesh.hexas27,quads=built.preview_quads,
+                            mesh_dimension=3,mode_extension=1,displacement_components=3,component_labels=['ux','uy','uz'],mesh_view_axes=[0,2])
+        _front_plot(built,out/'disp_field.png','Displacement magnitude / m',np.linalg.norm(displacement,axis=1));check()
+        _front_plot(built,out/'phi_field.png','Potential real part / V',potential.real)
+        fig,ax=plt.subplots(figsize=(7,4));ax.plot(frequencies*1e-9,np.abs(y));ax.set_xlabel('Frequency / GHz');ax.set_ylabel('|Y| / (S/m)')
+        ax.set_title('2.5D periodic slice; normalized by aperture');ax.grid(alpha=.3);fig.tight_layout();fig.savefig(out/'Y11.png',dpi=150);plt.close(fig)
+        meta.update(peak_frequency_ghz=float(frequencies[peak]*1e-9),peak_is_boundary=peak in [0,len(y)-1],field_selection='maximum sampled admittance magnitude')
+    else:meta['task_kind']='mesh'
+    check();meta['elapsed_seconds']=time.time()-started;atomic_json(out/'metadata.json',meta)
+    names=['input.json','material_snapshot.json','metadata.json','mesh.npz','material_data.npz','mesh.png','manifest.json']
+    if not mesh_only:names += ['curve.json','admittance.npz','admittance.csv','fields.npz','disp_field.png','phi_field.png','Y11.png']
+    artifacts=[dict(name=name,kind='image' if name.endswith('.png') else 'data',media_type={'.png':'image/png','.json':'application/json','.csv':'text/csv','.npz':'application/octet-stream'}[Path(name).suffix]) for name in names]
+    manifest=ResultManifest(model_id=cfg.model_id,artifacts=artifacts).model_dump();atomic_json(out/'manifest.json',manifest)
+    progress('完成',1 if mesh_only else cfg.points,'complete');return manifest

sawsim/material_catalog.py

@@ -0,0 +1,49 @@
+"""Dynamic material catalog, with legacy constants retained for compatibility."""
+from copy import deepcopy
+
+SUBSTRATES = [
+    {'id':'sp_baseline','name':'压电基板 · 基准数据集 I',
+     'description':'复用原单层 SP 完整张量，密度 7450 kg/m³。保留历史数值；原代码 LN 标签不能作为已核实的材料身份。'},
+    {'id':'linbo3_tc','name':'LiNbO₃ · TC-SAW 数据集',
+     'description':'复用原 TC-SAW 完整 6×6/3×6/3×3 张量，密度 4628 kg/m³。源数据已在其参考器件坐标系；输入欧拉角是相对该参考系的附加旋转，不代表已核实晶圆切型。'},
+]
+ELECTRODES = [
+    {'id':'al_hex35','name':'Al 铝（ν = 0.35）','description':'各向同性：E = 70 GPa，ν = 0.35，ρ = 2700 kg/m³；e = 0，ε = ε₀I。用于 2.5D 四层模板，与 ν = 0.33 数据集并列保留。'},
+    {'id':'al','name':'Al 铝（ν = 0.33）','description':'各向同性：E = 70 GPa，ν = 0.33，ρ = 2700 kg/m³；e = 0，ε = ε₀I。'},
+    {'id':'cu','name':'Cu 铜','description':'各向同性：E = 120 GPa，ν = 0.34，ρ = 8960 kg/m³；e = 0，ε = ε₀I。'},
+]
+LAYER_MATERIALS = [
+    {'id':'si_cubic_hex','name':'Si 硅 · 立方各向异性','description':'立方晶系：C11 = 166、C12 = 64、C44 = 80 GPa；ρ = 2330 kg/m³，εr = 11.68。'},
+    {'id':'polysi_160','name':'Poly-Si 多晶硅（E = 160 GPa）','description':'各向同性：E = 160 GPa，ν = 0.22，ρ = 2320 kg/m³，εr = 4.5。用于 2.5D 四层模板。'},
+    {'id':'si_aniso_hex','name':'Si 硅 · 各向异性全张量','description':'完整 6×6 刚度张量；ρ = 2330 kg/m³，εr = 11.8。用于 2.5D 四层模板。'},
+    {'id':'si_isotropic','name':'Si 硅 · 各向同性近似','description':'各向同性近似：E = 170 GPa，ν = 0.28，ρ = 2329 kg/m³，εr = 11.7。'},
+    {'id':'sio2','name':'SiO₂ 二氧化硅','description':'各向同性：E = 70 GPa，ν = 0.17，ρ = 2200 kg/m³，εr = 4.2。'},
+    {'id':'polysi','name':'Poly-Si 多晶硅（E = 169 GPa）','description':'各向同性：E = 169 GPa，ν = 0.22，ρ = 2320 kg/m³，εr = 4.5。'},
+    {'id':'sin','name':'Si₃N₄ 氮化硅','description':'各向同性：E = 160 GPa，ν = 0.23，ρ = 3100 kg/m³，εr = 9.7。'},
+]
+
+EULER_CONVENTION = {
+    'id':'zxz',
+    'description':'内禀 ZXZ 欧拉角：α、β、γ（API 字段 phi、theta、psi）将所选材料数据的源参考系映射至器件全局坐标系。角度单位为度；旋转作用于压电衬底及使用该材料的 PML。各向同性电极不受角度影响。TC-SAW 源数据已经过参考系旋转；统一角度约定不会自动对齐不同源晶轴、模型坐标或命名晶圆切型。',
+    'formula':'A = Rz(α) Rx(β) Rz(γ); C′ = M C Mᵀ, e′ = A e Mᵀ, ε′ = A ε Aᵀ; Rz(t)=[[cos(t),-sin(t),0],[sin(t),cos(t),0],[0,0,1]], Rx(t)=[[1,0,0],[0,cos(t),-sin(t)],[0,sin(t),cos(t)]]; M is the Voigt stress transformation [xx,yy,zz,yz,xz,xy].',
+    'units':'deg',
+    'legacy_conversion':'(α, β, γ) = (-ψ_old, -θ_old, -φ_old)',
+    'reference':'内禀 ZXZ 欧拉角（z-x′-z″），与主流有限元软件的旋转坐标系定义一致；矩阵形式见 formula 字段。',
+}
+
+
+def get_material_catalog():
+    from sawsim.material_library import list_records, record_hash
+    records = list_records()
+    # list_records sorts numeric-aware versions ascending; expose one current
+    # choice per id. Explicit historical versions remain available in registry.
+    latest = {record['id']: record for record in records}
+    catalog = {'substrates': [], 'electrodes': [], 'layers': [],
+               'euler_convention': deepcopy(EULER_CONVENTION)}
+    groups = {'substrate': 'substrates', 'electrode': 'electrodes', 'layer': 'layers'}
+    for record in latest.values():
+        entry = dict(record, hash=record_hash(record),
+                     versions=[r['version'] for r in records if r['id'] == record['id']])
+        for role in record['roles']:
+            catalog[groups[role]].append(deepcopy(entry))
+    return catalog