Developer guide: update for #106; add a gold-nanoparticle tutorial

[kavyawadhwa134]

Brings PYTHON_DEVELOPER_GUIDE.md and its PDF in line with #106 (atomic de-excitation restored; app.generator works with n_threads > 0).

Rewritten for #106

• Section 17: the template now configures the source with app.generator under n_threads=4. The initialize() and /gun/ workaround is gone.
• Section 28: the source is configured the same way in both modes. Generator settings made before initialize() are kept and applied at initialization. A mistyped /gun/ or /gps/ command issued that early is reported by initialize() or the first run().
• Section 32: the "Primary generator action is not available" entry now applies to 0.2.0 only. A new entry covers missing fluorescence x-rays: the 0.2.0 bug with the custom list, and production cuts with the reference lists (deexcitationIgnoreCut, /run/setCut, fluo for FTFP_BERT).
• Section 75 (Generator): drops "serial run manager only".
• Section 82: the test list now includes tests/test_physics.py.

New tutorial 71: dose enhancement by gold nanoparticles

• Model: a 2 mm tumour of A-150 loaded with 1% or 2% gold by mass (a GDML mixture of G4_A-150_TISSUE and G4_Au), 1 cm deep in an A-150 block.
• Beam: a broad, parallel GPS photon beam at 50, 100, 250 and 1000 keV, 10 batches × 100k photons per configuration, multithreaded.
• Comparison: the dose ratio and its batch uncertainty against NIST μen/ρ. Figure in docs/images/gold_nanoparticles.png.

E [keV]	gold	Geant4	μen/ρ estimate
50	1%	2.586 ± 0.031	2.514
100	1%	1.857 ± 0.015	1.813
100	2%	2.740 ± 0.021	2.626
250	1%	1.121 ± 0.013	1.102
1000	1%	1.007 ± 0.016	1.001

Before #106, 1% gold at 100 keV gave about 2.7. With fluorescence switched off after initialize(), this setup gives 2.87 ± 0.02.

The enhancement (ratio − 1) is 4–7% above the estimate at 50 and 100 keV:

• Not phantom scatter: with no phantom, 2% gold at 100 keV still gives 2.72 ± 0.03.
• Gold L x-rays: μen/ρ counts them as escaping, but the 2 mm tumour absorbs many of them. In a 0.2 mm tumour the same case gives 2.59 ± 0.03, against 2.63 expected.

Adding the tutorial renumbers sections 71–86 to 72–87, and their cross-references were updated with them.

Finding (Geant4 11.4.3): a GDML mixture with a 0.0000 gold fraction does not behave like plain A-150 at 1 MeV. Its tumour dose is about 40% higher (10.2 vs 7.2 keV/g per photon), in serial and multithreaded runs. So the reference tumour uses G4_A-150_TISSUE directly, and the tutorial says so.

Verification

Built main from source against Geant4 11.4.3 (MT) in a fresh venv:

• tests/test_physics.py and tests/test_run.py pass: 9 passed, 1 skipped (the skip is an existing MT skip).
• The section 17 and 28 snippets run with n_threads > 0.
• The section 32 claims were checked on a 0.1 mm gold slab at 100 keV.
• The tutorial script was rerun and its output reproduced exactly.
• pre-commit passes (prettier, blacken-docs, codespell). The PDF was rebuilt with tools/build_guide_pdf.py (663 KB).

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a0747289-67f4-43d6-8258-b5b22bd88aef

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}