[yonghakim]

What changes

Five independent changes found while preparing #142, the pure 1D TE/TM path. Each is its own self-contained commit. This branch starts from main 93cf7cb, not from #142, so the two PRs land independently.

1. fix(rcwa): a jitted run of the Jones pair (0, 1) no longer aborts the process.
   • The symptom: jax.jit of a public rcwa run with PlaneWave(polarization=(0., 1.)) killed Python under jit and jit(grad) on jax/jaxlib 0.11.0. It raised no exception.
   • The cause: the prepared run's nonzero-polarization guard (_lifecycle._runtime_checks) took xp.abs(a)**2. XLA's algebraic simplifier reads the complex constant [0, 1] as an iota and rewrites abs(iota) to the iota itself, which has the wrong (complex) type. The compile then fails a RET_CHECK in HandleAbs.
   • The fix: the guard now takes real(a * conj(a)). Its truth value is the same.
2. fix(migration): a v10 tetm declaration migrates to the word for the same light.
   • migrate_legacy_jobs read old.tetm.name, but the v10 reader stores the word 'te'/'tm', so every v10 document that declared tetm raised AttributeError.
   • It now maps through the reader's own normalizer: 'te' becomes 's' and 'tm' becomes 'p'.
3. docs: two statements that treated tetm as current.
   • solver-integration.md named a wavebit.Tetm that does not exist.
   • Chapter 12's "incident and output polarization" section stated s_inc/p_inc and tetm= in the present tense. It now gives the current reading and keeps the earlier interface in a marked box, in English and Korean.
4. test(rcwa): tests/rcwa/test_boundary.py asks for JAX double precision itself.
   • The symptom: under pytest-xdist, 11 of its tests computed their JAX solves in float32 and failed, though the file passes alone.
   • The cause: importing the private JAX backend lifts JAX's 32-bit cap, but not inside a public run's Execution scope, which suppresses that lift on purpose. A worker whose first JAX test was a public single-precision run therefore left x64 off for every later engine JAX solve.
   • The fix: the file calls _enable_x64() at import, guarded for an absent JAX, as test_laurent_factorization.py already does.
5. docs(learn): chapter 12 reads results through the current API, in English and Korean.
   • It now uses rcwa.run, the ports' order(m, n) with .efficiency / .amplitude_s / .amplitude_p, the (wavelength, order_v, order_u) shape, orders_u/orders_v, k_parallel/k_normal, reference['plane'], outputs['power_entering'] and absorption.
   • The earlier spellings move into "Earlier interface" boxes, and the chapter note is gone.
   • Every printed value was re-measured, with each snippet run as written. The values are unchanged.

Verification

• Abort fix.
  • The repro now runs under jit, jit(grad), vmap and grad, and its jitted R matches the eager NumPy value to 1e-12.
  • The new test test_jit_of_the_jones_pair_0_1_compiles_instead_of_aborting runs the jitted call in a subprocess and fails with the old guard restored.
  • The same script ran on main and on this branch and gave 184 arrays, all bit-identical: amplitudes, efficiencies, powers, fields, S blocks, jit/grad/vmap values, torch gradients and single precision.
• Migration. test_a_tetm_declaration_migrates_to_the_word_for_the_same_light covers 'te', 'tm' and 'TM'. It holds R, T and all four s/p amplitudes against the original v10 run to 2e-13, and all three cases fail with the old line restored.
• test_boundary. A scratch pytest plugin ran a public single-precision JAX run at session start. In that order, the three failing tests that were run all failed before the fix, and all eleven pass after it. The whole file passes in that order (97/97) and alone.
• Chapter 12. The snippets were run as written on Chapter 4's grating: 0.2053, 0.3531, 0.7947, (1, 1, 21), and |t_s(0, 0)| = 0.4852 at 115.5°.
• Docs. sphinx-build -W -b html docs builds clean, and tests/api/test_docs_contract.py passes (166).
• Public lifecycle files, default tier (26 files, not slow and not research, 4 workers), on the first three commits: 1240 passed, 11 failed. All 11 failures are in tests/rcwa/test_boundary.py, and commit 4 fixes them.
• Environment: conda env wavebit, Python 3.12.9, numpy 2.5.1, jax/jaxlib 0.11.0, torch 2.14.1, macOS arm64.

Not done

• Once this PR and rcwa: a polarization word takes the pure 1D TE/TM path #142 have both landed, tests/api/test_unified_rcwa_pure_1d.py can write that pair as (0, 1) again instead of (0, 2). That is a one-line follow-up.

🤖 Generated with Claude Code