cwt3d 1.0.0__tar.gz

cwt3d-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hai HUANG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cwt3d-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE README.md README.pypi.md pyproject.toml
+recursive-include src/cwt3d *.py
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include benchmarks *.py
+recursive-include scripts *.py
+recursive-include docs *.md *.json *.csv *.png
+# These two files are parsed, not imported, by historical-defect tests.
+include model/_Model.py calculator/_calc.py
+global-exclude __pycache__ *.py[cod] .DS_Store

cwt3d-1.0.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: cwt3d
+Version: 1.0.0
+Summary: Independent numerical core for three-dimensional coupled-wave theory
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maple367/3D-CWT
+Project-URL: Documentation, https://github.com/maple367/3D-CWT/blob/latest/docs/api.md
+Project-URL: Issues, https://github.com/maple367/3D-CWT/issues
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: numba
+Requires-Dist: numba>=0.61; extra == "numba"
+Dynamic: license-file
+
+# cwt3d
+
+A Python implementation of three-dimensional coupled-wave theory for
+square-lattice photonic-crystal surface-emitting lasers (PCSELs).
+
+The package calculates normalized vertical TE waveguide modes, Fourier
+coupling coefficients, and finite-cavity envelopes using sparse staggered-grid
+eigenproblems. Runtime dependencies are NumPy and SciPy; COMSOL is not required.
+
+## Install
+
+```bash
+python -m pip install cwt3d
+```
+
+Matplotlib is optional:
+
+```bash
+python -m pip install "cwt3d[plot]"
+```
+
+## Examples and Python interfaces
+
+The [source repository](https://github.com/maple367/3D-CWT) includes a complete
+70 × 70 µm² circular-hole example based on Chapter 4 of Yong Liang's thesis.
+It contains the layer stack, runnable calculation and plotting scripts, and
+numerical refinement results.
+
+![70 µm PCSEL envelope](https://raw.githubusercontent.com/maple367/3D-CWT/latest/docs/images/liang-70um.png)
+
+The [Python API guide](https://github.com/maple367/3D-CWT/blob/latest/docs/api.md)
+shows how to construct a different geometry, calculate its coupling matrix,
+solve a finite cavity, and access the complex fields. Examples are included
+in the source distribution and repository; the wheel installs the `cwt3d`
+library.
+
+## Scope
+
+The current model uses lossless scalar TE waves on a square lattice.
+It returns modes near a selected complex shift, not the complete cavity
+spectrum. The example's auxiliary-harmonic refinement is still finite, as
+reported in its notes. Carrier transport and above-threshold dynamics from
+the historical application are not part of this package.
+
+The code is distributed under the MIT license. The formulation follows
+[Yong Liang's doctoral thesis](https://doi.org/10.14989/doctor.k18283);
+references and conventions are listed in the repository documentation.

cwt3d-1.0.0/README.md

@@ -0,0 +1,190 @@
+# 3D-CWT
+
+Three-dimensional coupled-wave calculations for square-lattice photonic-crystal
+surface-emitting lasers (PCSELs). The Python package calculates the vertical
+waveguide mode, the four-wave coupling matrix, and finite-cavity modes on a
+staggered grid.
+
+The current optical solver uses NumPy and SciPy. It does not require COMSOL.
+The original COMSOL-based code and its version notes are retained below.
+
+## Example: a 70 µm square cavity
+
+This example uses the circular-hole (CC) structure from Chapter 4 of
+[Yong Liang's doctoral thesis](https://doi.org/10.14989/doctor.k18283),
+Table 4.1: a 295 nm square lattice, 16% air filling fraction, and a
+70 × 70 µm² cavity. The figure shows a calculated single-lobed mode and its
+center-line intensity profiles.
+
+![Calculated envelope intensity in the 70 µm square cavity](docs/images/liang-70um.png)
+
+The plotted quantity is the slowly varying envelope
+`|Rx|² + |Sx|² + |Ry|² + |Sy|²`, divided by its peak. The numerical results,
+layer stack, and refinement checks are in the
+[70 µm example notes](docs/examples/liang-70um.md).
+
+## Install and run
+
+Run these commands from the repository root.
+Python 3.10 or later is required. The `plot` extra installs Matplotlib for the
+figure; the calculation itself only needs NumPy and SciPy.
+
+```bash
+python -m pip install -e ".[plot]"
+python examples/liang_70um.py --N 96 --D 32 --q 64 --output results/liang-70um
+python examples/plot_liang_70um.py results/liang-70um
+```
+
+The first script writes `summary.json`, `modes.csv`, and `fields.npz`. The second
+writes `selected_mode.png`. Choose a new output directory for each calculation;
+the solver refuses to overwrite an existing result.
+
+For a quicker first run, use the lower-order defaults:
+
+```bash
+python examples/liang_70um.py --output results/liang-70um-quick
+```
+
+`--N` is the number of envelope-grid cells per side, `--D` is the auxiliary
+Fourier cutoff, and `--q` is the vertical integration order. They control
+different numerical errors. The quick run and the plotted run use the same
+physical structure.
+
+## Use the calculation from Python
+
+The example exposes the calculation as a function. Run this from the repository
+root after installation:
+
+```python
+from examples.liang_70um import run_case
+
+case = run_case(N=96, D=32, q=64)
+mode = case.modes[0]
+
+print("delta L:", mode.delta * 70)
+print("alpha L:", mode.alpha * 70)
+print("eigenpair residual:", mode.residual)
+
+intensity = mode.intensity       # shape: (Ny, Nx)
+Rx = mode.centers.Rx             # complex envelope at cell centers
+C = case.coupling.C              # 4 x 4 coupling matrix, in µm^-1
+A, B = case.pencil.A, case.pencil.B
+```
+
+`run_case` returns the waveguide reference, coupling matrix, sparse pencil,
+eigenpairs, reconstructed fields, and a summary dictionary. Pass `output=...`
+to save them. To build a different structure or reuse a coupling matrix, follow
+the [complete Python API example](docs/api.md).
+
+The default search targets one mode near the lowest-frequency periodic band
+edge. `--k` and `--sigma` select a larger set or a different part of the
+spectrum; one search is not a survey of all competing modes. Eigenvalues are
+`delta + 1j*alpha`, where `alpha` is an amplitude-loss coefficient. Power loss
+is `2*alpha`.
+
+## Documentation
+
+- [Running examples and reading the output](docs/usage.md)
+- [Python interfaces and a complete custom calculation](docs/api.md)
+- [70 µm structure, results, and numerical checks](docs/examples/liang-70um.md)
+- [Model conventions and earlier literature checks](docs/literature_validation.md)
+- [Numerical tests](docs/validation.md) and [performance measurements](docs/performance.md)
+- [Publishing releases to PyPI](docs/publishing.md)
+
+The current model covers lossless scalar TE waves on a square lattice. The
+70 µm calculation uses a layered outgoing Green function and halfspace
+claddings, so it is a calculation with the thesis structure rather than an
+exact reproduction of the thesis curves. Carrier transport and above-threshold
+laser dynamics are not included in the new package.
+
+To run the tests:
+
+```bash
+python -m pip install -e ".[dev,plot]"
+python -m pytest -q
+```
+
+---
+
+## Previous versions (v2)
+
+# 3D-CWT
+ Three Dimension Coupled Wave Theory
+
+# Requirements
+- Python 3.12 (my environment)
+    - numpy=1.26.4
+    - scipy=1.14.0
+    - matplotlib
+    - mph
+    - dill
+- Comsol Multiphysics
+## Installation
+```bash
+conda env create -f environment.yml
+```
+
+# TODO
+- [x] Add support for titled photonic crystal
+- [x] Add support for finite size photonic crystal
+- [ ] Add find_beta0 and find_k0 to class TMM
+- [ ] Pure python implementation
+
+# Release Notes
+## Latest - Version 2.0.0
+ - Organize the code.
+## Version 1.3.0
+ - Use high accuracy Green's function.
+## Version 1.2.0
+ - Consider the symmetry of the fourier coefficients, so that the calculation of the fourier coefficients is faster.
+## Version 1.0.0
+ - Add support for finite size photonic crystal. Powered by [Comsol Multiphysics](https://www.comsol.com/).
+## Version 0.4.1
+ - Encapsulated into a function.
+## Version 0.4.0
+ - Add support for titled photonic crystal.
+ - Add comsol semiconductor simulation.
+## Version 0.3.0
+ - Turn back to Python as numerical computing environment.
+## Version 0.2.0
+ - Use Matlab as numerical computing environment.
+
+# Citing 3D-CWT
+If you use this code in your research, please cite the following papers, this will help me a lot.  
+In BibTeX format:  
+```bibtex
+@article{huang_Efficient_2026,
+  title = {Towards Efficient {{PCSEL}} Design: A Fully {{AI-driven}} Approach},
+  shorttitle = {Towards Efficient {{PCSEL}} Design},
+  author = {Huang, Hai and Xu, Ziteng and Xin, Qi and Zhang, Zhaoyu},
+  journal = {Chinese Optics Letters},
+  volume = {24},
+  number = {4},
+  pages = {043602},
+  year = 2026,
+  doi = {10.3788/COL202624.043602},
+  langid = {english}
+}
+
+@article{huang_Unveiling_2025,
+  title = {Unveiling the Potential of Photonic Crystal Surface Emitting Lasers: A Concise Review},
+  shorttitle = {Unveiling the Potential of Photonic Crystal Surface Emitting Lasers},
+  author = {Huang, Hai and Yang, Chuanyi and Li, Hui and Zhang, Zhaoyu},
+  year = 2025,
+  month = apr,
+  journal = {Semiconductor Science and Technology},
+  volume = {40},
+  number = {4},
+  pages = {43001},
+  publisher = {IOP Publishing},
+  issn = {0268-1242, 1361-6641},
+  doi = {10.1088/1361-6641/adb7fd},
+  langid = {english}
+}
+```
+or in following IEEE format:  
+[1] H. Huang, C. Yang, H. Li, and Z. Zhang, ‘Unveiling the potential of photonic crystal surface emitting lasers: a concise review’, Semicond. Sci. Technol., vol. 40, no. 4, p. 43001, Apr. 2025, doi: 10.1088/1361-6641/adb7fd.  
+[2] H. Huang, Z. Xu, Q. Xin, and Z. Zhang, ‘Towards efficient PCSEL design: a fully AI-driven approach’, Chinese Optics Letters, vol. 24, no. 4, Art. no. 043602, 2026, doi: 10.3788/COL202624.043602.
+
+
+

cwt3d-1.0.0/README.pypi.md

@@ -0,0 +1,47 @@
+# cwt3d
+
+A Python implementation of three-dimensional coupled-wave theory for
+square-lattice photonic-crystal surface-emitting lasers (PCSELs).
+
+The package calculates normalized vertical TE waveguide modes, Fourier
+coupling coefficients, and finite-cavity envelopes using sparse staggered-grid
+eigenproblems. Runtime dependencies are NumPy and SciPy; COMSOL is not required.
+
+## Install
+
+```bash
+python -m pip install cwt3d
+```
+
+Matplotlib is optional:
+
+```bash
+python -m pip install "cwt3d[plot]"
+```
+
+## Examples and Python interfaces
+
+The [source repository](https://github.com/maple367/3D-CWT) includes a complete
+70 × 70 µm² circular-hole example based on Chapter 4 of Yong Liang's thesis.
+It contains the layer stack, runnable calculation and plotting scripts, and
+numerical refinement results.
+
+![70 µm PCSEL envelope](https://raw.githubusercontent.com/maple367/3D-CWT/latest/docs/images/liang-70um.png)
+
+The [Python API guide](https://github.com/maple367/3D-CWT/blob/latest/docs/api.md)
+shows how to construct a different geometry, calculate its coupling matrix,
+solve a finite cavity, and access the complex fields. Examples are included
+in the source distribution and repository; the wheel installs the `cwt3d`
+library.
+
+## Scope
+
+The current model uses lossless scalar TE waves on a square lattice.
+It returns modes near a selected complex shift, not the complete cavity
+spectrum. The example's auxiliary-harmonic refinement is still finite, as
+reported in its notes. Carrier transport and above-threshold dynamics from
+the historical application are not part of this package.
+
+The code is distributed under the MIT license. The formulation follows
+[Yong Liang's doctoral thesis](https://doi.org/10.14989/doctor.k18283);
+references and conventions are listed in the repository documentation.

cwt3d-1.0.0/benchmarks/bench_coupling.py

@@ -0,0 +1,74 @@
+"""Run from repository: .venv/Scripts/python.exe benchmarks/bench_coupling.py --cache-dir <explicit path>."""
+from common import *
+import argparse
+from scipy.optimize import linear_sum_assignment
+from cwt3d.coupling import build_coupling
+from cwt3d.greens import LayeredGreen, PreparedLayeredGreen
+from cwt3d.cache import CouplingCache
+
+
+def eigen_error(a,b):
+    x,y=np.linalg.eigvals(a),np.linalg.eigvals(b)
+    i,j=linear_sum_assignment(abs(x[:,None]-y))
+    return float(max(abs(x[i]-y[j])))
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--cache-dir',required=True)
+    parser.add_argument('--output',default='docs/benchmarks')
+    parser.add_argument('--repeats',type=int,default=3)
+    args=parser.parse_args()
+    if args.repeats < 1: parser.error('repeats must be positive')
+    rows=[]
+    cache=CouplingCache(args.cache_dir)
+    for dual in (False,True):
+        mode,a,holes=physical(dual)
+        # Explicit, measured initialization and steady evaluation, not JIT compile.
+        z=np.linspace(.01,.12,12)[:,None]; s=np.linspace(.015,.125,12)[None,:]
+        kernel_times={}
+        for name,cls in [('reference',LayeredGreen),('prepared',PreparedLayeredGreen)]:
+            kernel,init=timed(lambda:cls.from_structure(mode.guide),args.repeats)
+            kernel(z,s)
+            _,steady=timed(lambda:kernel(z,s),args.repeats)
+            _,scalar=timed(lambda:cls.from_structure(mode.guide)(.05,.07),args.repeats)
+            kernel_times[name]=dict(init_samples_seconds=init,init_median_seconds=float(np.median(init)),
+                                    steady_samples_seconds=steady,steady_median_seconds=float(np.median(steady)),
+                                    scalar_cold_samples_seconds=scalar,scalar_cold_median_seconds=float(np.median(scalar)))
+        for D in (1,3,10):
+            options=dict(cutoff=D,quadrature_order=12,fourier_order=64)
+            call=lambda backend,q=12:build_coupling(mode,a,holes,**dict(options,quadrature_order=q),backend=backend)
+            # Each backend gets one unrecorded warm-up; all reported samples retained.
+            call('reference'); call('prepared')
+            ref,rs=timed(lambda:call('reference'),args.repeats)
+            fast,fs=timed(lambda:call('prepared'),args.repeats)
+            # Independent higher-q reference, never lower accuracy to gain speed.
+            high,hs=timed(lambda:call('reference',24),1)
+            middle=call('reference',18)
+            key=cache.key(mode,a,holes,backend='prepared',**options)
+            cache.clear(key)  # exact owned key only, ensures actual cold miss
+            cold,cs=timed(lambda:cache.build(mode,a,holes,backend='prepared',**options),1)
+            hit,ch=timed(lambda:cache.build(mode,a,holes,backend='prepared',**options),args.repeats)
+            assert cold == hit == fast
+            row=dict(geometry='dual_circle_triangle' if dual else 'single_circle',cutoff=D,
+                     quadrature_order=12,fourier_order=64,convergence_reference_q=24,
+                     repeats=args.repeats,warmup_per_backend=1,
+                     reference_samples_seconds=rs,prepared_samples_seconds=fs,
+                     reference_median_seconds=float(np.median(rs)),prepared_median_seconds=float(np.median(fs)),
+                     speedup=float(np.median(rs)/np.median(fs)),
+                     matrix_max_error=float(np.max(abs(ref.C-fast.C))),eigen_set_max_error=eigen_error(ref.C,fast.C),
+                     q12_vs_q24_matrix_max_error=float(np.max(abs(ref.C-high.C))),
+                     q18_vs_q24_matrix_max_error=float(np.max(abs(middle.C-high.C))),
+                     q12_vs_q24_eigen_set_max_error=eigen_error(ref.C,high.C),
+                     q24_reference_samples_seconds=hs,
+                     cache_miss_seconds=cs[0],cache_hit_samples_seconds=ch,cache_hit_median_seconds=float(np.median(ch)),
+                     kernel_timings=kernel_times,radial_count=len(ref.radial_orders),
+                     cache_cleanup='exact key removed after measurement')
+            rows.append(row)
+            cache.clear(key)
+            save(args.output,'coupling',rows,accuracy='Same D/q/F/geometry and Duffy triangles; eigenvalues Hungarian matched.',
+                 cache_policy='Explicit directory only; measured keys deleted. Scratch host policy prunes entries idle 24h.')
+            print(json.dumps({k:row[k] for k in ('geometry','cutoff','speedup','matrix_max_error','q12_vs_q24_matrix_max_error')}),flush=True)
+    assert len(rows)==6
+
+if __name__=='__main__': main()

cwt3d-1.0.0/benchmarks/bench_finite.py

@@ -0,0 +1,58 @@
+"""Sparse finite-domain scaling; no dense or legacy mathematical baseline."""
+from common import *
+import argparse
+import tracemalloc
+from cwt3d.coupling import build_coupling
+from cwt3d.finite.grid import StaggeredGrid
+from cwt3d.finite.assembly import FinitePencil
+from cwt3d.finite.eigensolver import solve_finite
+
+
+def run(grid,coupling):
+    start=perf_counter(); pencil=FinitePencil(grid,coupling); assembly=perf_counter()-start
+    start=perf_counter()
+    eigen=solve_finite(pencil,sigma=.03+.03j,k=6,tol=1e-9,residual_tol=1e-9,seed=33,ncv=30,maxiter=5000)
+    solve=perf_counter()-start
+    a,b=pencil.A,pencil.B
+    shifted=(a-(.03+.03j)*b).tocsc()
+    return dict(assembly_seconds=assembly,solve_total_seconds=solve,
+                lu_seconds=eigen.lu_seconds,iteration_seconds=eigen.iteration_seconds,
+                max_residual=float(max(eigen.residuals)),nnz_A=a.nnz,nnz_B=b.nnz,
+                nnz_shift=shifted.nnz,lu_nnz=eigen.lu_nnz,lu_fill_ratio=eigen.lu_nnz/shifted.nnz,
+                linear_solves=eigen.linear_solves,status=eigen.status,
+                eigenvalues=[[float(x.real),float(x.imag)] for x in eigen.eigenvalues])
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--output',default='docs/benchmarks')
+    parser.add_argument('--repeats',type=int,default=3)
+    args=parser.parse_args()
+    if args.repeats < 1: parser.error('repeats must be positive')
+    m,a,h=physical(True)
+    c=build_coupling(m,a,h,cutoff=3,quadrature_order=12,fourier_order=64,backend='prepared')
+    rows=[]
+    for n in (8,16,32):
+        grid=StaggeredGrid(n,n,40.,40.)
+        run(grid,c)  # warm-up independent of timing/memory samples
+        samples=[run(grid,c) for _ in range(args.repeats)]
+        tracemalloc.start()
+        memory_run=run(grid,c)
+        _,peak=tracemalloc.get_traced_memory(); tracemalloc.stop()
+        row=dict(Nx=n,Ny=n,n_dof=grid.n_dof,Lx_um=40.,Ly_um=40.,sigma=[.03,.03],
+                 k=6,tol=1e-9,residual_tol=1e-9,seed=33,ncv=30,maxiter=5000,
+                 repeats=args.repeats,warmup=1,samples=samples,
+                 tracemalloc_peak_bytes=peak,rss_peak_bytes=None,
+                 memory_note='Separate traced run: Python/registered NumPy allocations, NOT process RSS or full native LU memory.',
+                 memory_run_max_residual=memory_run['max_residual'])
+        for key in ('assembly_seconds','solve_total_seconds','lu_seconds','iteration_seconds','lu_fill_ratio'):
+            row[key+'_median']=float(np.median([sample[key] for sample in samples]))
+        for key in ('nnz_A','nnz_B','nnz_shift','lu_nnz','linear_solves','max_residual','status'):
+            row[key]=samples[len(samples)//2][key]
+        rows.append(row)
+        save(args.output,'finite',rows,coupling=dict(geometry='dual_circle_triangle',cutoff=3,quadrature_order=12,fourier_order=64,backend='prepared'),
+             scope='Sparse scaling only, same target controls; no dense/legacy speed claim, no cross-grid mode matching or mesh-convergence claim.')
+        print(json.dumps({k:row[k] for k in ('Nx','assembly_seconds_median','lu_seconds_median','iteration_seconds_median','max_residual','tracemalloc_peak_bytes')}),flush=True)
+    assert len(rows)==3
+
+if __name__=='__main__': main()

cwt3d-1.0.0/benchmarks/common.py

@@ -0,0 +1,58 @@
+"""Shared deterministic fixtures and non-identifying benchmark output."""
+import os
+# Set before importing NumPy/SciPy. Override inherited multi-thread settings.
+THREAD_VARIABLES = ('OPENBLAS_NUM_THREADS','MKL_NUM_THREADS','OMP_NUM_THREADS',
+                    'VECLIB_MAXIMUM_THREADS','NUMEXPR_NUM_THREADS','BLIS_NUM_THREADS')
+for name in THREAD_VARIABLES:
+    os.environ[name] = '1'
+import csv
+import json
+from pathlib import Path
+import platform
+from time import perf_counter
+import numpy as np
+import scipy
+from cwt3d.geometry import CircleHole, RightTriangleHole
+from cwt3d.waveguide import TEWaveguide
+
+
+def physical(dual=False):
+    means = [8.,10.] if dual else [9.]
+    guide = TEWaveguide([1., *means, 1.], [.13,.19] if dual else [.32], k0=6.)
+    mode = guide.solve_mode()
+    a = 2*np.pi/mode.beta
+    fill = np.pi*.13**2
+    first = CircleHole(.13*a,(a,a),(.36*a,.47*a), means[0]+2*fill, means[0]-2*(1-fill))
+    holes = {1:first}
+    if dual:
+        fill = .35*.27/2
+        holes[2] = RightTriangleHole((.35*a,.27*a),(a,a),(.63*a,.54*a),
+                                     means[1]+2*fill,means[1]-2*(1-fill))
+    return mode,a,holes
+
+
+def environment():
+    from cwt3d.cache import algorithm_digest
+    return dict(source_digest=algorithm_digest(),python=platform.python_version(),numpy=np.__version__,scipy=scipy.__version__,
+                system=platform.system(),release=platform.release(),machine=platform.machine(),
+                cpu=platform.processor(),logical_cpus=os.cpu_count(),
+                threads={name:os.environ[name] for name in THREAD_VARIABLES},
+                precision='complex128',jit='N/A (no JIT)',rss_peak_bytes=None,
+                note='Thread environment fixed before importing NumPy; RSS not measured.')
+
+
+def timed(call, repeats):
+    samples=[]
+    for _ in range(repeats):
+        start=perf_counter(); result=call(); samples.append(perf_counter()-start)
+    return result,samples
+
+
+def save(output, kind, rows, **extra):
+    output=Path(output); output.mkdir(parents=True,exist_ok=True)
+    data=dict(kind=kind,environment=environment(),rows=rows,**extra)
+    (output/f'{kind}.json').write_text(json.dumps(data,indent=2,allow_nan=False)+'\n',encoding='utf-8')
+    keys=list(dict.fromkeys(k for row in rows for k in row))
+    with (output/f'{kind}.csv').open('w',newline='',encoding='utf-8') as stream:
+        writer=csv.DictWriter(stream,fieldnames=keys); writer.writeheader()
+        writer.writerows({k:json.dumps(v) if isinstance(v,(list,dict)) else v for k,v in row.items()} for row in rows)