Skip to content

Model SHG in a Type I crystal in the forward models - #31

Open
chrisbrahms wants to merge 16 commits into
LupoLab:mainfrom
chrisbrahms:feature/shg-crystal-core
Open

chrisbrahms wants to merge 16 commits into
LupoLab:mainfrom
chrisbrahms:feature/shg-crystal-core

Conversation

@chrisbrahms

Copy link
Copy Markdown
Contributor

What changed

The first part of #24: SHG in a Type I (oo→e) uniaxial crystal, through the NumPy and JAX forward models.

  • croak.crystals.
    • UniaxialCrystal holds any pair of ordinary and extraordinary index functions, with an optional transparency range.
    • CrystalSetup takes the cut angle with either an external tilt or the wavelength the crystal was tuned to phase-match (the tilt is then solved). It also takes the crossing geometry and the fundamental's polarisation relative to the crossing plane.
    • propagation gives the fundamental's (ordinary, longitudinal) and the signal's (extraordinary, at the internal angle) propagation constants, the ω/n generation prefactor and the path through a tilted plate.
    • depth_points gives the depth nodes the phase mismatch needs, and the models refuse fewer.
  • croak.geometry.TwoBeamGeometry. It is the one source of the crossing angle: beam separation and focal length, and later the beam diameter for smearing.
  • The forward models. ForwardModel, maketrace and the JAX trace functions accept a CrystalSetup as material for SHG, with separate fundamental and signal propagators. The refusal of a material for SHG is lifted only for a crystal; PG and SD are unchanged.
  • Beams crossing in the crystal's principal plane. The signal's tilt changes its index to first order. The model keeps that term as opposite delay drifts of the two arms (CrystalSetup.arm_shift), with the delayed beam's side as a parameter (delayed_beam); the two sides mirror the trace in delay. The drift is referenced to mid-depth, so the trace keeps its delay origin (Reference the principal-plane delay drift to mid-depth? croak's crystal trace is offset by κP from a full-field simulation #28). tilt_field_error and check_tilt estimate what the first-order treatment leaves out and warn above 1 %.
  • Docs. The forward-model manual has a new section on SHG in a Type I crystal. It covers the two propagation constants, the generation prefactor, depth resolution, the signal's tilt and its walk-off picture, and where the drift is referenced, with the argument and its assumptions. The tutorial and the interactions page point to it, and there is a changelog fragment.

Not in this PR: threading the crystal through the solvers, session and GUI, BBO from optmat (PR 3b), and two-beam SHG delay smearing (PR 4). Both follow as stacked PRs once this is in. Fitting the crystal's thickness stays refused for SHG (#26).

Verification

  • uv run poe check on the final commit: lint, format, pyright (0 errors), codespell, changelog check, and the full suite with 100 % statement and branch coverage.
  • uv run poe docs builds without warnings.
  • Tests (all with a synthetic BBO-like Sellmeier pair; no new dependency):
    • the n_e(θ) limits and derivative;
    • the solved tilt phase-matches its wavelength;
    • both models against an exact double sum over component pairs (analytic depth integral), for both geometries;
    • the exact marginal identity, M(Ω) = |a_s|² Σ S S sinc²(ΔkL/2);
    • the depth-node rule;
    • NumPy against JAX;
    • the zero-thickness limit (the ideal trace times the prefactor);
    • the hand-derived adjoint against finite differences, and against JAX;
    • the drift's sign (flipping it mirrors the trace in delay);
    • that the principal-plane trace keeps its delay origin (fails with an exit-face reference);
    • every refusal and error path.
  • Against a full-field simulation (Luna.jl, 2-D x–t, the full χ(2) field of two crossing Gaussian beams in BBO, the signal summed over the whole beam): for a 10 fs pulse with 30 fs² of GDD in 100 µm at 1.43°, and a 6 fs pulse with 20 fs³ in 30 µm at 2.86°, the model matches to 1.2 % and 0.2 % of the trace peak. That is with the delay smearing averaged in, for beams crossing at the entrance face, mid-plane or exit face. Out of the principal plane the traces are symmetric, as the model predicts. Run, not public.
  • Two rounds of independent review on each block (the crystal numerics, the forward models, the drift's reference), with the findings fixed.

Coefficient checks: the tests use a synthetic Sellmeier pair (Tamošauskas et al. 2018's BBO coefficients, as printed) only as a realistic test crystal; no physical constant is transcribed into the package by this PR.

Related

Part of #24. Closes #28. Follow-ups: #25 (crystal-aware marginal check), #26 (fitting the crystal), #27 (remaining differences against a full-field simulation). Independent of #29.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WM2AxPM9w8Mg7mfKikaeCX

chrisbrahms and others added 15 commits November 12, 2026 17:05
croak.crystals supplies separate propagation constants for the ordinary
fundamentals (with the crossing angle) and the extraordinary signal near
2*omega0, and the omega_s/n_s generation prefactor; keeping the carrier
wavevectors, the depth sum carries the exact phase mismatch. The crystal
is given by its cut angle and an external tilt, or the wavelength it is
tuned to. croak.geometry holds the two-beam geometry, the one source of
the crossing angle. Both forward models take a CrystalSetup for SHG and
check the depth resolution and the neglected signal tilt.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
The exact double sum over component pairs with the depth integral done
analytically, the Parseval form of the frequency marginal (pair sinc^2),
the zero-thickness limit, NumPy against JAX, the hand adjoint, the guards,
and the neglected signal tilt against a per-pair reference.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
The worst pair over the whole grid sits at its edges, where there is no
light, and overstated the error some 200-fold. tilt_phase_error takes the
fundamental's band (spectral_band), and check_tilt warns once the band is
known; the forward models, which do not know the field, no longer warn.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
- Integrate over the effective path of a tilted plate,
  L / (cos g + (n_e'/n_e) sin g), the first-order normal mismatch; tested
  against an exact normal-component solve.
- A crystal's transparency range: outside it the signal is absorbed and
  pairs do not drive the depth-node count.
- Guards: omega0 > 0, a reachable tilt, an internal angle in 0-90 degrees,
  thickness >= 0, Gauss-Legendre quadrature.
- check_tilt computes the neglected signal tilt's actual change to the
  signal over a set of delays (tilt_field_error, by the exact pair sum)
  and warns above 1 %; at zero delay its first-order effect cancels.
- Independent tests of the crossing wavevector, a tilted forward model and
  the masks; docs and comments corrected.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Crossing in the crystal's principal plane, the signal of a pair (w1, w2)
leaves at an angle psi to the bisector, solving (w_s/c) n_e(theta + psi)
sin(psi) = k_x; its index changes to first order, adding the mismatch
kappa (w1 - w2), kappa = (n_e'/n_s) sin(alpha) / c. That factorises into
opposite delays of the two arms that drift with depth, now carried by
separate test and gate propagators in both forward models and the
adjoint. The trace is then asymmetric in delay; CrystalSetup.delayed_beam
sets the sign, which flipping mirrors the trace in delay. The reference
for check_tilt solves the signal's direction self-consistently and
measures what is left (second order). The phase bound and band helper
are gone.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Test the JAX hand adjoint with the arms' drift; pin the side flip to the
delay mirror exactly on grid-aligned delays; reject a tilt beyond grazing,
a non-finite thickness and an all-zero amplitude; write n_e'/n_s and the
arms' delays explicitly; note what depth_points and the tilt reference
leave out; correct two figures in the manual and a typo in the fragment.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
The 0.5 % came from delays too coarse for a 5 fs pulse; sampled finely it
is about 1 %. The manual now gives which arm gets which delay, and
tilt_field_error refuses an empty set of delays.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
The first-order signal-tilt term is the extraordinary SH walking off
across the transverse delay gradient of the crossing beams. Say so in the
manual and the module docstring, and stop describing walk-off as
neglected: only the SH beam's sideways shift out of the overlap is.

Refs LupoLab#24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Two modules on the core API page had a section called Validity, which
Sphinx rejects as a duplicate ID.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Referenced to the exit face, the drift offset the model's trace by kappa*P
in delay, which a full-field simulation collecting the whole beam does not
show (LupoLab#28). The part of the walk-off common to every depth moves the whole
SH beam sideways, which full collection cannot see; the plane-wave model
drops the walk-off between depths, least on average about the mean
generation depth, which is mid-depth for a uniform slab.

The exact pair-sum reference re-references only the first-order drift, so
tilt_field_error is not made smaller by the choice. A new test pins the
trace's delay origin; the manual gives the argument, its assumptions and
the full-field evidence, and the recomputed effect of the drift.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxMiUXc12ViRwSf2cyL
kappa is about 6e-12 s/m, below pytest.approx's default absolute tolerance
of 1e-12, so the relative tolerance was not what the test checked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxPM9w8Mg7mfKikaeCX
@chrisbrahms chrisbrahms added enhancement New feature or request area: forward model Forward models, interactions, dispersion, smearing and collection labels Nov 13, 2026
@read-the-docs-community

read-the-docs-community Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

The pair-mismatch estimate kept a pair when |w1 + w2| <= max|omega|, a strict
float comparison at exactly the edge bins. The solver rebuilds its grid from the
trace's frequency axis, whose spacing can differ from the session's in the last
bit, so the two counted different pairs and the solver refused a node count the
session had computed (25 against 27 for 200 um of BBO). Test the sum against the
grid's own span with half a bin of tolerance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WM2AxPM9w8Mg7mfKikaeCX

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: forward model Forward models, interactions, dispersion, smearing and collection enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Reference the principal-plane delay drift to mid-depth? croak's crystal trace is offset by κP from a full-field simulation

1 participant