Repository map

Primary solver and optimizers

File	Role
`vector3d_optimizer.py`	Yee Maxwell operator, PML, topology parameterization, periodic-lead surface Green functions, fixed-frequency LDOS gradient, profiles, memory estimator, and boundary checks.
`shifted_optimizer.py`	Real-axis local pole continuation driver and implicit pole-Q or shifted-LDOS optimization.
`loewner_optimizer.py`	Differentiable scalar Loewner pole-Q surrogate with AAA/linewidth acceptance.
`overlap_optimizer.py`	Seven-probe, wide/local, overlapping-mode trust-region optimizer.
`atom_ldos_optimizer.py`	Centered atom-projected LDOS/Purcell optimizer with homogeneous normalization, shifted real-axis Loewner proposals, parallel provisional gradients, constrained MMA/adaptive trust, and fail-closed fixed-atom/shifted/Q/shared-pole acceptance.
`accelerated_cooperativity.py`	Shifted-cooperativity and detuning chain rules, conservative separable moving-asymptote dual, and adaptive trust-radius policy.
`refine_checkpoint.py`	Controlled topology transfer between grids by fitting the projected density.
`prepare_symmetry_checkpoint.py`	Topology-only transfer into the reflection-closed exact y/z parity backend; deliberately carries no pole or Q.

Spectral acquisition and validation

File	Role
`frequency_search.py`	Sparse broad real-frequency resonance search.
`pole_validation.py`	Local real-axis nonlinear-pole continuation and Fano-linewidth validation.
`rational_pole_validation.py`	Scalar AAA rational continuation with held-out frequencies.
`multiprobe_sweep.py`	Restartable real-frequency sweep of seven linear field observables.
`multipole_validation.py`	Shared-pole variable-projection fits and SIMO Loewner checks for overlapping modes.
`local_upper_validation.py`	Dense local upper-mode model-family diagnostics.
`combined_rational_validation.py`	Authoritative merged wide/local, seven-probe, four-holdout spectral gate.

PML and field diagnostics

File	Role
`pml_convergence.py`	Local-continuation transverse-PML sweep.
`rational_pml_convergence.py`	Scalar rational transverse-PML sweep.
`multipole_pml_convergence.py`	Shared-pole PML gate; use `--validator combined` for the current mode cluster.
`field_diagnostics.py`	Driven-field localization and air-strip/inner-defect energy proxies.

Tests

Every test_*.py file is part of the regression suite. test_vector3d.py covers the discrete Maxwell/boundary core; the remaining tests cover spectral fits, gradients, checkpoint transfer, PML aggregation, and optimizer logic.

Run all tests with:

python -m unittest discover -v

requirements.txt gives supported minimum direct dependencies; requirements-tested.txt records the exact direct versions used for this handoff's 30-test run.

Documentation

File	Purpose
`START_HERE.md`	Entry point and immediate goal.
`AGENTS.md`	Non-negotiable operating and evidence rules.
`DERIVATIONS.md`	Full mathematical derivation and approximation ledger.
`SCIENTIFIC_STATUS.md`	Accepted evidence, missing gates, and claim boundaries.
`WORKSTATION96_RUNBOOK.md`	Exact 96 GB commands and stop conditions.
`CODEX_SETUP.md`	Install/login/model/permission guidance for command-line Codex.
`REFERENCES.md`	Foundational papers/software and their role in the architecture.
`README.md`	Architecture, historical results, and command overview.
`MILESTONE4_REPORT.md` ... `MILESTONE7_REPORT.md`	Development history and results.
`ENVIRONMENT_MEMORY.md`	Measured/estimated resource history and an important eliminated dense-self-energy failure.
`ATOM_COUPLING_OBJECTIVE.md`	Continuous atom-LDOS definition, discrete normalization, gradient, acceptance tests, and limitations.
`SHIFTED_COOPERATIVITY_ARCHITECTURE.md`	Exact-lead-compatible shifted objective, gradient, normalization, MMA constraints, and independent acceptance contract.
`OPTIMIZATION_ACCELERATION_REPORT.md`	Accepted fine-grid shifted-MMA demonstration, PML evidence, adjacent-step performance comparison, and gradient benchmark.
`SYMMETRY_ACCELERATION.md`	Exact y/z electromagnetic parity formulation, equivalence tests, fine-grid speed/memory measurements, current accepted evidence, and x-reduction limitation.
`PUBLISH.md`	Static documentation/dashboard publishing instructions for the preconfigured Contabo route.
`UNATTENDED_RUNBOOK.md`	Fail-closed one-command fine-grid cooperativity step, restart behavior, fixed protocol, and terminal dashboard handling.
`expand_x_checkpoint.py`	Geometry-only x expansion by whole periodic-mirror periods with phase-matched explicit lead initialization.
`scripts/qualify_domain_transfer.py`	Fresh wide/dense-local/confirmatory spectral qualification and controller seed creation after a domain transfer.
`scripts/bootstrap_xlong_persistent.py`	Restartable transfer -> spectral -> PML bootstrap followed by the unbounded fail-closed controller.
`scripts/run_persistent_cooperativity.sh`	Production entry point for the expanded-x no-step-limit campaign.

Checkpoints and key artifacts

Path	Meaning
`outputs_bragg_loewner_step4/`	Final accepted coarse Q=200.33 checkpoint.
`outputs_bragg_q200_refined_workstation64/`	Controlled transverse-refinement checkpoint (`20 x 18 x 14`).
`outputs_refined_multiprobe/`	41-point wide seven-probe controlled-grid sweep.
`outputs_refined_multiprobe_mode_b/`	29-point dense local seven-probe controlled-grid sweep.
`outputs_refined_combined_rational_validation/`	Authoritative controlled-grid Q=921.65 spectral result.
`outputs_refined_field_diagnostics/`	Controlled-grid field-localization evidence.
`outputs_refined_fine_workstation64_checkpoint/`	Geometry transferred to `40 x 26 x 22`; starting point for the 96 GB run.
`outputs_refined_fine_yz_symmetry_checkpoint/`	Topology-identical transfer into the exact y/z backend; no spectral state carried.
`outputs_fine_yz_symmetry_multiprobe_wide/`	Fresh 41-point, seven-probe spectrum on the y/z backend.
`outputs_fine_yz_symmetry_multiprobe_local_dense113/`	Fresh 113-point dense local spectrum on the y/z backend.
`outputs_fine_yz_symmetry_multiprobe_confirmatory28/`	Independent 28-point confirmatory spectrum on the y/z backend.
`outputs_fine_yz_symmetry_combined_validation_confirm28_order29_32/`	Retained failed combined validation; this is a candidate, not a spectrally accepted result.
`outputs_fine_yz_symmetry_multiprobe_local_dense449/`	Full 449-point local reacquisition resolving the target's single-sheet interval and adjacent lead branch edges.
`outputs_fine_yz_symmetry_multiprobe_confirmatory28_sheetlocal/`	Separately solved prescribed 28-point sheet-local confirmatory grid.
`outputs_fine_yz_symmetry_combined_sheetlocal_dense449_confirm28/`	Authoritative accepted fine-grid target-pole spectral result.
`outputs_fine_yz_symmetry_combined_pml_sheetlocal_v2/`	Passed seven-case baseline/transverse-PML campaign for the fine input topology.
`outputs_atom_cooperativity_yz_step1/`	First accepted unattended common-ascent atom-LDOS/Q step, fresh spectra, checkpoint, geometry, and field.
`outputs_atom_cooperativity_yz_step1_rejected_q_decrease/`	Retained pure-LDOS trial that passed spectral fitting but was rejected because Q decreased.
`outputs_atom_cooperativity_long/step_0001/`	Second accepted legacy common-ascent step and its checkpoint-bound spectral/PML evidence.
`outputs_shifted_mma_demo/step_0001/`	First fully accepted shifted constrained-MMA step, promotion, seven-case PML gate, timing, and A/B benchmark artifacts.
`outputs_atom_cooperativity_xlong_persistent/`	Expanded `64 x 26 x 22` topology-only transfer, fresh bootstrap evidence, and persistent campaign checkpoints. Its transfer subdirectory carries no pole or Q.

Other output directories are retained because they document intermediate milestones or rejected model/PML behavior. Do not delete them before the fine-grid campaign is safely archived elsewhere.

Checkpoint schema

The exact keys vary by stage, but a normal output directory contains:

run_data.npz: raw design variables, density/field data, and tracking state;
config.json: the complete Maxwell/grid configuration;
metrics.json or checks.json: machine-readable conclusions;
history.csv: optimization or continuation history when applicable;
a Markdown report; and
one or more PNG diagnostics.

Keep run_data.npz and config.json together. A raw design vector is not meaningful without its topology mask, filter, projection, grid, and mirror phase.