fix: confocal excitation at the excitation wavelength; redesign PSF pipeline, add acquisition tracks and laser channels

[tlambert03]

This started as fix to make point scanning confocal use the excitation wavelength for the PSF instead of emission. Fixing that properly meant pulling apart how modalities, channels and PSFs fit together, so this ended up being a redesign of the simulation → modality → PSF pipeline.

The model now:

• Modalities are now responsible for creating system PSF = excitation spot × detection PSF. The spot is computed at the excitation wavelengths (several lines for multiple lasers/broadband sources, binned by width via the new Settings.excitation_bin_width_nm); the detection PSF is computed at the emission wavelengths and convolved with an anti-aliased pinhole mask (so small pinholes don't snap to whole pixels).
• brightness is separate from PSF shape. Each channel × fluorophore gets a detected photon rate (photons/s per fluorophore) and the PSFs carry only shape. Saturation (E / (1 + sE)) is applied locally across the spot, so it's strongest at the center. A nice side effect: changing laser power no longer recomputes PSFs (0.12 s vs 1.84 s on main).
• pinhole size in Airy units is defined at the emission filter band center, so one channel has one physical pinhole (rather than a different pinhole per emission wavelength bin). Confocal.airy_unit_wavelength_nm overrides that.

Tracks (sequential vs. simultaneous acquisition). The previous model assumed sequential channel acquisition, (with broadband light sources that still can result in bleedthrough). On a real point scanner you often choose which channels are acquired together. Simulation.tracks now models that:

sim = Simulation(
    ...,
    channels=[LASER_405, LASER_488, LASER_561, LASER_640],
    tracks=[[0, 2], [1, 3]],  # by index or channel name, or "sequential"/"simultaneous"
)

• default is "sequential": each channel is excited only by its own light, which is what main did.
• within a track, every laser excites every fluorophore, so you get realistic bleedthrough.
• each item is a Track (bare lists are cast), so we have a place to put per-track settings later (pinhole, dwell, averaging, power...).
• a laser shared by channels in a track is counted once, and channels must agree on its power/dichroic. Point-scanner channels in a track must also share a dwell time.
• Confocal.shared_pinhole (default True) shares one pinhole within a track.

Lasers and examples. Added LASER_405/445/488/515/561/640 channels to the library (laser + dichroic + emission bandpass), and went through all the confocal examples/notebooks/docs so they use laser lines, real fluorophores, HyD detectors and realistic powers and dwell times, rather than broadband filter cubes with the mock fluorophore. For reference, power is the peak irradiance at the focus: 1e5 W/cm² is ~50 µW at NA 1.4. The README example now uses a 0.6 AU pinhole (0.2 AU was very photon-starved).

Also fixed along the way:

• an off-grid laser line (e.g. 488.5 nm) gave exactly zero excitation (inner join against the 1 nm grid). Spectrum * Spectrum now interpolates onto the union of both grids.
• the lowest-wavelength emission sample was dropped from PSF weights (widefield is now 0.4-5.5% brighter).
• detector QE wasn't applied to channels without an emission filter.

The PSF implementation moved to a private microsim._psf module. microsim.psf keeps the same public functions as on main (make_psf, make_confocal_psf, vectorial_*...). I'd like to move the rest of the accidentally-public stuff there in a future PR.

Breaking changes

There are a lot here... the next release v0.0.13 will absolutely be breaking. but it's always been part of the contract here for this early dev project:

• all confocal output changes (excitation wavelength, pinhole definition, local saturation).
• filtered_emission_rates() / emission_flux() apply saturation by default (new saturate= keyword).
• removed microsim.psf.cached_psf, Modality.psf(), and point_scanning; Modality.render() has a new signature.
• cached PSF arrays are read-only (make_psf returns a copy).
• Identity output follows settings.float_dtype (float32 by default).
• confocal warns for channels without a band-limited emission filter, and raises if a track's pinhole detects no light.
• new fields on Simulation, Confocal and Settings, so JSON saved with this version won't load in older ones.
• PSF disk cache layout changed (old cached PSFs are just orphaned, not misread).

Performance

Same speed as main, within noise. Peak memory is up ~0.1-0.2 GB (3-6%):

	main	this PR
README confocal, cold PSF cache	2.68 s / 3.81 GB	~2.7 s / 4.01 GB
README confocal, warm disk cache	1.10 s	1.05 s
widefield, cold	2.28 s	2.15 s
4 channels × 2 fluors, cold	6.55 s	6.30 s

Known limitations / follow-ups

• pinhole throughput depends on pixel size. The pinhole mask area is now exact, but the emission PSF is still sampled at the voxel size, so at coarse pixels the light through a small pinhole is off: at 0.5 AU, -12% at dx=0.1 µm and +27% at 0.2 µm (vs 0.02 µm). The fix is probably computing the detection PSF on a finer grid before the pinhole convolution.
• the confocal PSF radius is a fixed 8 AU (unchanged from main). It doesn't account for pinhole size or depth, so it clips a bit of out-of-focus excitation in thick volumes and some light from large pinholes.
• each channel uses its own dichroic, even within a track (a real scanner has one multiband dichroic per track).

[codecov]

Codecov Report

❌ Patch coverage is 98.22785% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.96%. Comparing base (1773a2e) to head (5fe0ebb).

Files with missing lines	Patch %	Lines
src/microsim/psf.py	90.90%	3 Missing ⚠️
src/microsim/schema/optical_config/config.py	90.00%	2 Missing ⚠️
...rc/microsim/schema/optical_config/_fluorescence.py	98.24%	1 Missing ⚠️
src/microsim/schema/simulation.py	98.70%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #160      +/-   ##
==========================================
+ Coverage   88.26%   89.96%   +1.70%     
==========================================
  Files          49       51       +2     
  Lines        3316     3569     +253     
==========================================
+ Hits         2927     3211     +284     
+ Misses        389      358      -31     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.