Metadata-Version: 2.5
Name: pyrite-mc
Version: 0.13.5
Summary: Coherent X-ray radiation and electron transport in crystals.
Project-URL: Homepage, https://github.com/Quantum-Light-Matter-Cooperative-QLMC/pyrite#readme
Project-URL: Repository, https://github.com/Quantum-Light-Matter-Cooperative-QLMC/pyrite
Project-URL: Documentation, https://pyrite.readthedocs.io/en/latest/
License: Academic Software License: © 2026 UCLA (“Institution”). Academic or nonprofit researchers are permitted to use
        this Software (as defined below) subject to Paragraphs 1-4:
        
        1. Institution hereby grants to you free of charge, so long as you are an academic or nonprofit researcher,
            a nonexclusive license under Institution’s copyright ownership interest in this software and any derivative
            works made by you thereof (collectively, the “Software”) to use, copy, and make derivative works of the
            Software solely for educational or academic research purposes, and to distribute such Software free of charge
            to other academic or nonprofit researchers for their educational or academic research purposes, in all cases
            subject to the terms of this Academic Software License. Except as granted herein, all rights are reserved
            by Institution, including the right to pursue patent protection of the Software.
        
        2. Any distribution of copies of this Software -- including any derivative works made by you thereof --
            must include a copy (including the copyright notice above), and be made subject to the terms, of this
            Academic Software License; failure by you to adhere to the requirements in Paragraphs 1 and 2 will result
            in immediate termination of the license granted to you pursuant to this Academic Software License effective
            as of the date you first used the Software.
        
        3. IN NO EVENT WILL INSTITUTION BE LIABLE TO ANY ENTITY OR PERSON FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
            OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE, EVEN IF INSTITUTION
            HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. INSTITUTION SPECIFICALLY DISCLAIMS ANY AND ALL WARRANTIES,
            EXPRESS AND IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
            A PARTICULAR PURPOSE. THE SOFTWARE IS PROVIDED “AS IS.” INSTITUTION HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
            SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS OF THIS SOFTWARE.
        
        4. Any academic or scholarly publication arising from the use of this Software or any derivative works thereof
            will include the following acknowledgment:  The Software used in this research was created by Alexander Amador and
            Nicholas Farhadian of UCLA. © 2026 UCLA.
        
        Commercial entities: please contact alexanderjamador@gmail.com for licensing opportunities.
License-File: LICENSE.txt
License-File: THIRD-PARTY-NOTICES.md
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.13
Requires-Dist: backports-zstd>=1.7; python_version < '3.14'
Requires-Dist: click>=8.4.1
Requires-Dist: easygdf<3,>=2.1.1
Requires-Dist: endf-parserpy>=0.17.0
Requires-Dist: gemmi<0.8,>=0.7.5
Requires-Dist: h5py>=3.16.0
Requires-Dist: mpmath<2,>=1.3
Requires-Dist: numba>=0.66.0
Requires-Dist: numpy>=2.4.6
Requires-Dist: pandas>=3.0.3
Requires-Dist: platformdirs>=4.9
Requires-Dist: polars>=1.44.2
Requires-Dist: psutil>=7.2.2
Requires-Dist: scipy>=1.17.1
Requires-Dist: tabulate>=0.10.0
Requires-Dist: tomlkit>=0.13
Requires-Dist: tqdm>=4.68.2
Requires-Dist: xraydb>=4.5.8
Provides-Extra: amd
Requires-Dist: cupy>=13.4.0; extra == 'amd'
Provides-Extra: external-db
Requires-Dist: mp-api>=0.46; extra == 'external-db'
Provides-Extra: intel
Requires-Dist: dpctl>=0.22.1; extra == 'intel'
Requires-Dist: dpnp>=0.20.0; extra == 'intel'
Provides-Extra: nvidia
Requires-Dist: cupy-cuda13x[ctk]>=14.1.1; extra == 'nvidia'
Description-Content-Type: text/markdown

# PyRITE

A **Py**thon toolkit for **R**adiation from **I**nteractions and **T**ransport of **E**lectrons.

PyRITE is a Monte Carlo electron transport code for crystalline and amorphous
solids. Its transport model largely follows the well-validated PENELOPE code
system. Its main purpose is to predict tunable X-ray lines emitted when
electrons interact coherently with crystals: parametric X-ray radiation (PXR)
and coherent bremsstrahlung (CBS). Neither PENELOPE nor Geant4 models these
natively.

> [!IMPORTANT]
> PyRITE is unvalidated research code under active development. Absolute
> predictions are only as trustworthy as their entry in the
> [physics validation ledger](docs/validation/physics-validation-ledger.md).

The longer-term goal is a general-purpose electron transport and radiation
toolkit for 1 keV–100 MeV electrons, with native GPU acceleration, arbitrary
source, target, and detector geometries, and extensible physics. Against the
FORTRAN-based PENELOPE and the C++-based Geant4, PyRITE trades maturity for a
lower barrier to entry: it is plain Python, fast, and easy to extend. Electron
channeling in crystals below 100 MeV is under investigation.

- Source: <https://github.com/Quantum-Light-Matter-Cooperative-QLMC/pyrite>
- Documentation: <https://pyrite.readthedocs.io/en/latest/>

## Install

Requires Python ≥ 3.13. Python 3.13 installs `backports.zstd` automatically;
Python 3.14+ uses the standard-library implementation.

```bash
# Command-line tool in its own environment (recommended):
uv tool install pyrite-mc

# Or into the current environment, for use as a library:
pip install pyrite-mc
# OR
uv add pyrite-mc
```

Then fetch the reference data and check the install:

```bash
pyrite tables fetch    # pinned datasets and tables, about 100 MB
pyrite config setup    # optional: detect GPU hardware, save the backend
pyrite --help
```

`pyrite tables fetch` downloads EEDL, EADL, EPDL, SBETHE, ELSEPA, and BremsLib
data from public GitHub Releases; no GitHub token is needed. Run
`pyrite tables fetch --help` to list the individual datasets, or
`pyrite tables fetch NAME --archive PATH` to install one from a local archive.
In a notebook with no terminal (for example, jupyter), call `pyrite.fetch_tables()`,
which does the same as a bare `pyrite tables fetch`.

For tab completion, run `pyrite config completion install` and restart the
shell; with `uv tool`, run `uv tool update-shell` first so `pyrite` is on
`PATH`. See the [shell-completion guide](docs/guides/shell-completion.md).

### GPU acceleration

The base `pyrite-mc` package is CPU-only. Install at most one GPU extra by
adding it in brackets after the package name:

| Hardware | Extra    | Backend                 |
| -------- | -------- | ----------------------- |
| NVIDIA   | `nvidia` | CUDA CuPy               |
| AMD      | `amd`    | ROCm source-built CuPy  |
| Intel    | `intel`  | oneAPI `dpnp` + `dpctl` |

```bash
uv tool install pyrite-mc[nvidia]
```

The `amd` extra builds CuPy from source and needs `CUPY_INSTALL_USE_HIP=1` set
for the install command; ROCm support is entirely untested as of this writing;
Intel support is provisional, and FP64 operations are currently unsupported.

> [!NOTE]
> `uv` refuses to combine GPU extras, but `pip` does not check: installing
> two of them leaves conflicting CuPy builds in one environment.

`PYRITE_MC_BACKEND=auto|cpu|cuda|rocm|sycl` selects the array backend. See
[execution and acceleration](docs/computation/execution-and-acceleration.md)
for backend, precision, transport-core, and memory-policy controls.

### From a checkout

To work from source:

```bash
git clone https://github.com/Quantum-Light-Matter-Cooperative-QLMC/pyrite.git
cd pyrite
uv sync                       # creates .venv/; add --extra nvidia|amd|intel for a GPU
source .venv/bin/activate     # Windows: .venv\Scripts\activate
```

Commands in the README and user guides assume `pyrite` is on your `PATH`:
activate `.venv` in each shell, or install once with `uv tool install .`
(see the [shell-completion guide](docs/guides/shell-completion.md)).
Contributor and CI commands are in the [development workspace guide](docs/repo-design/development-workspace.md).

## Run

Outputs generated using the CLI default to `pyrite-output/<kind>/` in the current workspace.
For a fixed output home, run `pyrite config set workspace.root /path/to/workspace`
once. Subdirectories reuse the nearest existing output tree; see the
[output-home and migration rules](docs/guides/configuration-cookbook.md#choose-an-output-home).

`pyrite run` executes a resumable campaign over a named profile and writes
checkpoints under `pyrite-output/checkpoints/`:

```bash
# Smallest end-to-end demo (~1 min on CPU); writes component checkpoints.
pyrite run quickstart

# Analyze an existing checkpoint.
pyrite app analysis launch hopg

# Pixel-detector observations, and case / cross-material comparison.
pyrite app pixels launch hopg
pyrite app compare launch hopg

# Interactive transport and lattice viewer; no checkpoint required.
pyrite app viewer launch hopg

# Validation dashboard.
pyrite app validation launch
```

Full sweeps are heavy. Run them through
[PyRITE's remote workflow](docs/guides/running-on-a-cluster.md) or the portable
SLURM templates documented there. GPT `.gdf` electron-beam snapshots can be used
as a beam source; see [GDF beam import](docs/guides/gpt-gdf-beams.md).

### Profiles

A profile is a named campaign: thickness, energy, and tilt grids, electron
counts, beam and detector references, and material membership. PyRITE ships
light demo profiles that each exercise one feature and run locally in a minute
or two on CPU:

| Demo | Shows |
| --- | --- |
| `quickstart` | one HOPG case, incoherent PXR lines plus bremsstrahlung |
| `sweep_demo` | a small two-material energy x tilt sweep for the analysis app |
| `trajectory_demo` | `--trajectories` capture and VTK export |
| `coherent_demo` | coherent + incoherent emission in windowed line grids |
| `detector_demo` | a pixel detector behind a filter, with Poisson counts |
| `pixelated_detector_demo` | native Timepix3 pixel grid with ideal response and expected counts |
| `two_detector_demo` | two ideal scalar apertures at 90° and 135°, exposing raw spectra |
| `high_energy_demo` | a 1 MeV beam with the measured line-grid policy |
| `hopg_emittance_demo` | Courant-Snyder transverse beam phase space |

`standard` is also bundled: it is the catalog's base profile, which every
material's default scan ranges resolve from, and a full research-scale sweep.

```bash
pyrite profile list
pyrite profile show quickstart
pyrite profile numerics show quickstart
```

Bundled profiles are read-only. Profiles you create or edit live in your user
catalog layer, `profiles/NAME.toml` under the platform config directory
(`~/.config/pyrite/` on Linux; `pyrite config get catalog.user`), and are read
over the bundled catalog:

```bash
# Clone a demo, then replace its energy (keV) and thickness (Å) grids.
pyrite profile create my_scan --from quickstart --energy 30:60:10 --thickness 5000,20000
pyrite profile set my_scan --material hopg,hbn
pyrite profile numerics set my_scan --cxr-trials 2000
pyrite profile show my_scan
pyrite run my_scan -m hopg
```

A complete catalog of your own (materials, beams, detectors) is selected with
`pyrite config set catalog.path DIR`; profile edits then write there instead.

See [sweep profiles](docs/guides/sweep-profiles.md),
[external catalogs](docs/guides/external-catalog.md), and the
[profile settings map](docs/repo-design/profile-settings.md) for every field.

### Python API

For a single simulation with no files on disk, `Physics` chooses models and
`Numerics` controls sampling, energy grids, and execution:

```python
import pyrite as pr

beam = pr.Beam(
    energy_keV=30.0, transverse=pr.TransverseSpot(fwhm_x_mm=1.0), longitudinal=pr.PointBunch()
)
target = pr.Slab("hopg", thickness_ang=10_000.0, tilt_deg=30.0, footprint=pr.Footprint(5.0, 5.0))
detector = pr.Detector()
result = pr.simulate(
    beam,
    target,
    detector,
    physics=pr.Physics(),
    numerics=pr.Numerics(cxr_trials=450, brem_trials=100),
)
print(result.provenance["identity_digest"])
```

With the scalar `Detector` shown here, `simulate` returns emitted spectra in
photons per incident electron per eV per sr, plus run identification, and
neither reads nor writes a checkpoint. Detector response is not applied; apply
it to the spectra explicitly if needed. The
[Python API workflow](docs/guides/python-api-workflow.md) covers scenes,
sweeps, detector scoring, and persistence. Prefer `pyrite run` when you need
resumability, profiles, remote execution, or the analysis apps.

The generated [CLI reference](docs/repo-design/cli/cli-reference.md) documents
every command.

## Core physics

Pipeline: sampled electron beam → single-scattering electron transport →
per-segment PXR + CBS, incoherent bremsstrahlung, and characteristic lines →
photon escape → detector scoring.

- **[Electron transport](docs/physics/beam-transport/electron-transport.md):**
  independent piecewise-linear flights with explicit elastic collisions and
  condensed energy loss; deterministic by default, with optional Urban
  straggling. Elastic collisions sample ELSEPA partial-wave cross sections;
  collision stopping uses material-level SBETHE tables. Beamline space charge
  and secondary electrons are not modeled.
- **[Crystal source](docs/physics/materials/structure-factor.md):**
  phase-specific structures, complex atomic form factors, Debye-Waller factors,
  selected reflections, and optional mosaicity define the reciprocal-space
  coupling.
- **[Coherent lines](docs/physics/radiation-physics/coherent-radiation.md):**
  first-order kinematic Born PXR and CBS amplitudes are summed coherently within
  each transport segment, i.e. between elastic collisions that change the
  electron direction $\hat{\mathbf v}$. A collision-free flight may be
  subdivided to resolve CSDA energy and clock evolution; each segment uses one
  representative velocity. The in-medium Bragg resonance is
  $\omega = (\mathbf v\cdot\mathbf g)/[1 - \mathrm{Re}\lbrace n(\omega)\rbrace\,\hat{\mathbf n}\cdot\mathbf v]$.
  Dynamical diffraction and electron channeling are not modeled.
- **[Incoherent continuum](docs/physics/radiation-physics/bremsstrahlung.md):**
  the default is the direction-resolved BremsLib v2.0 double-differential cross
  section (`pyrite tables fetch bremslib`). Without those tables, a run warns
  and falls back to isotropic EEDL bremsstrahlung: the ENDF-6 MF=23/MT=527 total
  cross section times the normalized MF=26/MT=527 photon-energy density, also
  selectable as `bremsstrahlung_model="eedl"`. Unscreened Born Bethe-Heitler
  with an Elwert correction remains an optional backend.
- **[Characteristic lines](docs/physics/radiation-physics/characteristic-radiation.md):**
  electron-impact vacancies from EEDL subshell ionization cross sections relax
  through xraydb fluorescence yields with L-shell Coster-Kronig redistribution.
  Each line carries its natural-width Lorentzian and is scored as a separate
  incoherent component of the line spectrum.
- **[Photon transport](docs/physics/radiation-physics/photon-escape-and-dispersion.md):**
  straight-ray Beer-Lambert escape with the total narrow-beam coefficient
  (photoabsorption plus Rayleigh and Compton removal). Scattered photons leave
  the ray with no build-up, redirection, or re-emission; bulk refractive
  dispersion is passive; interface optics are omitted.
- **[Detector treatment](docs/physics/detectors/detector-response.md):** source
  spectra are evaluated in a fixed far-field direction. Solid-angle acceptance,
  aperture broadening, efficiency, and measured-energy redistribution are
  downstream steps.

By default PyRITE neglects interference between distinct flights and between
incident electrons. The optional
[`coherent`/`both` tracking policy](docs/physics/radiation-physics/coherent-emission.md)
keeps phase along each single-electron trajectory and adds inter-electron terms
weighted by the sampled bunch form factor.

The [physics model index](docs/physics/index.md) lists assumptions, model
variants, and conventions, with links to each implementation-level description.
Geometry follows the [tilt convention](docs/physics/geometry/tilt-convention.md).

## Data and outputs

`src/pyrite/data/catalog/` is the bundled catalog: crystals, media, materials,
beams, detectors, and demo profiles, one TOML file per object. Your own
profiles and their energy-grid artifacts live in the user catalog layer
(`catalog.user`). Settings live in `~/.config/pyrite/config.toml`, remembered
app state in `~/.local/state/pyrite/`, fetched data in `~/.local/share/pyrite/`,
and rebuildable caches in `~/.cache/pyrite/` (platform equivalents elsewhere). Phase-specific CIFs
live in `src/pyrite/data/cifs/`; loading is offline. `pyrite material validate`
checks the selected catalog.

Each checkpoint is `pyrite-output/checkpoints/<stem>/{line,brem,characteristic}.h5` plus a
`pyrite-output/checkpoints/<stem>/meta.json` manifest. Stored source spectra exclude detector
response unless a detector view applies it explicitly.

## Validation

The analytic core is cross-checked against Feranchuk et al. (2000) and Zhai et
al. (2025). Before scientific use, consult the
[validation ledger](docs/validation/physics-validation-ledger.md) for
claim-level status and the [validation methodology](docs/validation/methodology.md).

## References

Primary physics and data sources:

- I. D. Feranchuk, A. Ulyanenkov, J. Harada, and J. C. H. Spence, Parametric
  x-ray radiation and coherent bremsstrahlung from nonrelativistic electrons in
  crystals, *Phys. Rev. E* **62**, 4225 (2000).
  [doi:10.1103/PhysRevE.62.4225](https://doi.org/10.1103/PhysRevE.62.4225)
- Q. Zhai et al., Enhanced tunable X-rays from bulk crystals driven by
  table-top free electron energies, *Nat. Commun.* **16**, 11218 (2025).
  [doi:10.1038/s41467-025-66063-6](https://doi.org/10.1038/s41467-025-66063-6)
- F. Salvat, *PENELOPE-2024: A Code System for Monte Carlo Simulation of
  Electron and Photon Transport*, OECD NEA report NEA/MBDAV/R(2024)1 (2025).
- F. Salvat, A. Jablonski, and C. J. Powell, ELSEPA — Dirac partial-wave
  calculation of elastic scattering of electrons and positrons by atoms,
  positive ions and molecules, *Comput. Phys. Commun.* **165**, 157 (2005).
  [doi:10.1016/j.cpc.2004.09.006](https://doi.org/10.1016/j.cpc.2004.09.006)
- A. Poškus, Double and single differential cross sections of electron-atom
  bremsstrahlung at electron energies up to 30 MeV for Z = 1–100,
  *At. Data Nucl. Data Tables* **166**, 101734 (2025).
  [doi:10.1016/j.adt.2025.101734](https://doi.org/10.1016/j.adt.2025.101734)

The full bibliography (atomic data libraries, stopping powers, form factors,
and numerical methods) is on the
[published references page](https://pyrite.readthedocs.io/en/latest/references.html),
generated from [`docs/references.bib`](docs/references.bib).

## Status and license

Academic research code under active development, distributed under the
[UCLA Academic Software License](https://github.com/Quantum-Light-Matter-Cooperative-QLMC/pyrite/blob/main/LICENSE.txt)
for educational or academic research use by academic or nonprofit researchers.
For commercial licensing, contact the author listed in the license.
