☢️ nucleon

Complete nuclear physics simulation library for fission and fusion.

nucleon provides physically accurate, well-documented implementations of the fundamental equations governing nuclear fission and fusion — from the Bethe-Weizsäcker mass formula to Bosch-Hale fusion cross-sections and Lawson's criterion.

---

⚛️ Physics

Nuclear Fission

When a heavy nucleus (e.g., ²³⁵U) absorbs a neutron, it can split into two lighter fragments, releasing ~200 MeV of energy and 2-3 neutrons. These neutrons can trigger further fissions, creating a chain reaction. nucleon models:

• Binding energy via the semi-empirical mass formula (Bethe-Weizsäcker)
• Neutron cross-sections from ENDF/B-VIII.0 evaluated data
• Criticality — critical mass, k-effective, four-factor and six-factor formulas
• Point kinetics — 6 delayed neutron group equations with RK4 integration
• Decay chains — Bateman equations for U-238, U-235, Th-232 series
• Chain reactions — Monte Carlo neutron multiplication simulation

Nuclear Fusion

Light nuclei (D, T, ³He) can fuse at extreme temperatures (>100 million K), releasing energy. Achieving net energy gain requires meeting the Lawson criterion. nucleon models:

• Fusion cross-sections — Bosch-Hale parameterization (validated 0.5–5000 keV)
• Reactivity ⟨σv⟩ — Maxwellian-averaged, analytic and numerical
• Lawson criterion — Triple product evaluation and ignition conditions
• Power balance — Alpha heating, bremsstrahlung, transport losses, Q-factor
• Plasma physics — Beta, Debye length, Larmor radius, collision frequencies
• Confinement — ITER-98y2 (IPB98(y,2)) H-mode scaling, ICF model

---

🚀 Quick Start

pip install nucleon   # or: pip install -e ".[dev]"

Fission: Critical Mass

from nucleon.fission.criticality import critical_mass

result = critical_mass('U-235', enrichment=1.0, reflector='beryllium')
print(f"Critical mass: {result['critical_mass_kg']:.1f} kg")
# Critical mass: ~15 kg (reflected)

Fission: Binding Energy Curve

from nucleon.fission.binding_energy import binding_energy_per_nucleon

# Fe-56: peak of the binding energy curve
ba = binding_energy_per_nucleon(26, 56)
print(f"Fe-56: {ba:.2f} MeV/nucleon")  # ~8.79

Fusion: D-T Cross-Section

from nucleon.fusion.cross_sections import fusion_cross_section

sigma = fusion_cross_section('D-T', 64)  # keV
print(f"σ(D-T, 64 keV) = {sigma:.0f} mb")  # ~5000 mb

Fusion: Lawson Criterion

from nucleon.fusion.lawson import lawson_criterion

result = lawson_criterion(
    n=1e20,       # density (m⁻³)
    T_keV=25,     # temperature
    tau_E=3.7,    # confinement time (s)
    reaction='D-T',
    Q_target=10
)
print(f"Q = {result['Q_achieved']:.1f}")
print(f"Meets Q≥10: {result['meets_criterion']}")

Decay Chain Simulation

import numpy as np
from nucleon.fission.decay import decay_chain_simulation
from nucleon.units import YEAR_SECONDS

result = decay_chain_simulation(
    'U-238', initial_mass_g=1.0,
    time_points=np.linspace(0, 4.5e9 * YEAR_SECONDS, 100)
)
# result['atoms']['U-238']  — atom counts over time
# result['atoms']['Pb-206'] — stable end product

Reactor Kinetics

from nucleon.fission.kinetics import simulate_kinetics

result = simulate_kinetics(
    rho_history=[(0.0, 0.0), (0.5, 0.003)],  # reactivity ramp
    t_end=5.0, dt=0.001, fuel='U-235'
)
# result['neutron_pop']  — neutron population vs time

---

📊 Visualization

from nucleon.viz.plots import (
    plot_binding_energy_curve,
    plot_fusion_cross_sections,
    plot_reactivity,
    plot_fission_cross_sections,
)

fig, ax = plot_binding_energy_curve()
fig.savefig('binding_energy.png')

fig, ax = plot_fusion_cross_sections()
fig.savefig('fusion_xs.png')

---

📦 Module Overview

Module	Description
nucleon.constants	CODATA 2022 physical constants
nucleon.particles	Isotope database (masses, half-lives, spins)
nucleon.units	Unit conversions (MeV↔J, barn↔m², keV↔K, etc.)
nucleon.fission.binding_energy	Bethe-Weizsäcker semi-empirical mass formula
nucleon.fission.qvalue	Q-value calculations for nuclear reactions
nucleon.fission.cross_sections	Neutron cross-sections (ENDF/B-VIII.0 data)
nucleon.fission.criticality	Critical mass, k-eff, four/six-factor formula
nucleon.fission.kinetics	Point kinetics with 6 delayed neutron groups
nucleon.fission.chain_reaction	Monte Carlo chain reaction simulation
nucleon.fission.decay	Bateman equations, decay chains, activity
nucleon.fusion.cross_sections	Bosch-Hale fusion cross-sections
nucleon.fusion.reactivity	Maxwellian-averaged ⟨σv⟩
nucleon.fusion.lawson	Lawson criterion, triple product
nucleon.fusion.plasma	Plasma beta, Debye length, Larmor radius
nucleon.fusion.power_balance	Fusion power balance, ignition
nucleon.fusion.confinement	Tokamak (ITER-98y2) and ICF scaling
nucleon.viz.plots	Matplotlib visualizations

---

📚 References

• CODATA 2022: Tiesinga et al., NIST
• ENDF/B-VIII.0: Brown et al., Nuclear Data Sheets 148, 1 (2018)
• Bosch-Hale: H.-S. Bosch & G.M. Hale, Nuclear Fusion 32 (1992) 611–631
• AME2020: Wang et al., Chinese Physics C 45, 030003 (2021)
• ITER Physics Basis: Nuclear Fusion 39 (1999) 2175
• Keepin: "Physics of Nuclear Kinetics" (1965)
• Krane: "Introductory Nuclear Physics" (Wiley, 1988)
• Lamarsh: "Introduction to Nuclear Engineering" (4th ed.)
• NRL Plasma Formulary: Naval Research Laboratory (2019)
• IAEA Nuclear Data Services: https://www-nds.iaea.org/

---

🧪 Development

git clone https://github.com/quantumnic/nucleon.git
cd nucleon
pip install -e ".[dev]"
pytest tests/ -v

---

📄 License

MIT License — see LICENSE.

---

nucleon — Because understanding the atom shouldn't require a reactor license.