Skip to content

Releases: melekderman/PyEPICS

First Official Release - [1.0.0] — 2026-02-15

15 Feb 11:10
@melekderman melekderman
v1.0.0
865b834

Choose a tag to compare

View all tags
First Official Release - [1.0.0] — 2026-02-15 Latest
Latest

Overview

PyEPICS is a Python library for reading, converting, and querying the LLNL EPICS 2025 (Electron Photon Interaction Cross Sections) nuclear data. It parses ENDF-6 formatted files from three libraries — EEDL (electron), EPDL (photon), and EADL (atomic relaxation) — and produces structured HDF5 files optimised for the [MC/DC](https://github.com/CEMeNT-PSAAP/MCDC) Monte Carlo transport code.

  • Package name (PyPI): epics
  • Import name: pyepics
  • License: BSD-3-Clause
  • Python: ≥ 3.11

Data Pipeline

PyEPICS provides a complete data pipeline from download to transport-ready HDF5:

  1. Download ENDF source files from LLNL (automatic HTML scraping)
  2. Parse ENDF-6 files into structured Python dataclasses
  3. Validate physics constraints (monotonicity, non-negativity, probability normalisation)
  4. Write Raw HDF5 preserving original grids, breakpoints, and interpolation codes
  5. Write MCDC HDF5 with common energy grids, compressed PDF tables, and analytical small-angle scattering

The CLI tool epics (or python -m pyepics.cli) drives this pipeline.

ENDF Readers

Reader Library Sections Parsed
EEDLReader EEDL (electron) MF=23 cross sections (total, elastic, large-angle, bremsstrahlung, excitation, ionisation + 39 subshells), MF=26 angular distributions and energy spectra
EPDLReader EPDL (photon) MF=23 cross sections (total, coherent, incoherent, photoelectric + subshells, pair production), MF=27 form factors and scattering functions
EADLReader EADL (atomic) MF=28/MT=533 atomic relaxation — binding energies, electron occupancies, radiative and non-radiative transition probabilities

All readers support Z=1 (Hydrogen) through Z=100 (Fermium) with a full periodic table mapping up to Z=118 (Oganesson).

HDF5 Output Formats

Raw HDF5 (one file per library per element)

Preserves original ENDF energy grids, breakpoints, and interpolation law codes. Written to data/raw/electron/, data/raw/photon/, data/raw/atomic/.

MCDC HDF5 (one combined file per element)

Optimised for MC/DC transport code. Written to data/mcdc/. Each file (e.g. Fe.h5) contains electron, photon, and atomic relaxation data.

Key MCDC transformations:

  • All cross sections interpolated onto a common energy grid
  • Angular/energy distributions compressed into (energy_grid, energy_offset, value, PDF) tables via build_pdf
  • Small-angle elastic scattering cosine distributions computed analytically from screened Rutherford theory
  • Atomic transitions split into radiative/non-radiative groups with pre-computed fluorescence and Auger yields

High-Level Client API

from pyepics import EPICSClient

client = EPICSClient("data/mcdc/")
xs = client.get_cross_sections("Fe")

Plotting

Requires matplotlib (pip install "epics[plot]"):

Function Description
plot_cross_sections(client, element) Plot all cross sections for one element
compare_cross_sections(client, elements, label) Compare one cross section type across elements
plot_binding_energies(client, elements) Binding energy vs Z
plot_shell_binding_energies(client, element) Per-subshell bar chart for one element

Converter Public API

Function Description
convert_dataset_to_hdf5(dataset_type, source, output) Single-step ENDF → HDF5
create_raw_hdf5(dataset_type, source, output) Write raw (full-fidelity) HDF5
create_mcdc_hdf5(dataset_type, source, output) Write MCDC-optimised HDF5 (single library)
create_combined_mcdc_hdf5(Z, output, eedl_path, epdl_path, eadl_path) Write combined MCDC HDF5 with all three libraries

Constants & Data Dictionaries

  • NIST CODATA 2018 constants: FINE_STRUCTURE, ELECTRON_MASS, BARN_TO_CM2, PLANCK_CONSTANT, SPEED_OF_LIGHT, ELECTRON_CHARGE
  • Periodic table: Z=1–118, each with name and symbol
  • MF/MT reaction tables: ELECTRON_MF_MT (78 entries), PHOTON_MF_MT, ATOMIC_MF_MT — full human-readable descriptions
  • Section abbreviation maps: ELECTRON_SECTIONS_ABBREVS, PHOTON_SECTIONS_ABBREVS, ATOMIC_SECTIONS_ABBREVS
  • Subshell mappings: ELECTRON_SUBSHELL_LABELS (39 subshells, K → Q3), SUBSHELL_DESIGNATORS / SUBSHELL_DESIGNATORS_INV
  • MF field documentation: MF23, MF26, MF27, MF28 — ENDF field-level descriptions

Validation

Built-in physics validation with configurable strictness:

  • Atomic number range (1 ≤ Z ≤ 118)
  • Energy grid monotonicity
  • Non-negative cross sections
  • Cross section array shape consistency
  • Transition probability sum ≈ 1.0 (5% tolerance)

Backward Compatibility

The pyepics.pyeedl_compat module re-exports all symbols from the legacy pyeedl package with deprecation warnings. Old constant names (MF_MT, SECTIONS_ABBREVS, SUBSHELL_LABELS) are kept as aliases.

Dependencies

Dependency Required Extra
numpy ≥ 1.24 Yes —
h5py ≥ 3.8 Yes —
endf ≥ 0.1 Yes —
requests ≥ 2.28 No [download]
beautifulsoup4 ≥ 4.11 No [download]
pandas ≥ 2.0 No [pandas]
matplotlib ≥ 3.7 No [plot]

Test Suite

164 unit tests covering:

  • EEDL/EPDL/EADL readers and cross-section parsing
  • Raw HDF5 writer output structure and data fidelity
  • MCDC HDF5 writer output structure, common grid interpolation, PDF generation
  • Combined MCDC writer (all three libraries in one file, partial data, error handling)
  • Mapping completeness (all MF/MT entries have abbreviations)
  • Full pipeline round-trips (ENDF → reader → HDF5 → verify)
  • Docstring coverage for all public functions
Assets 2
Loading