Metadata-Version: 2.4
Name: mucoeff
Version: 1.0.0
Summary: Photon interaction cross section and atomic data for elements Z = 1 through Z = 100
License-Expression: MIT
License-File: LICENSE
License-File: LICENSE-DATA
Keywords: x-ray,photon,attenuation,cross sections,medical physics,radiation
Author: Gustavo Pacheco
Author-email: gustavo.pachecoguevara@radboudumc.nl
Requires-Python: >=3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Requires-Dist: numpy (>=2.0,<3.0)
Project-URL: Data License (CC-BY 4.0), https://creativecommons.org/licenses/by/4.0/
Project-URL: Repository, https://github.com/radboud-axti/mucoeff_python
Description-Content-Type: text/markdown

# MUCOEFF

Photon interaction cross section and atomic data for elements Z = 1 through Z = 100.

## Description

MUCOEFF provides photon interaction cross sections and atomic data for elements
from Z = 1 to Z = 100, and for photon energies from 1 keV to 50 MeV. It is a
Python port of the original MUCOEFF C code by Boone and Chavez.

The package includes an interpolation routine and supports both scalar and
vectorized energy inputs. Available data include:

* X-ray mass attenuation coefficients: total, photoelectric, Rayleigh,
  Compton, pair production, and triplet production
* Energy transfer and energy absorption coefficients
* Density and atomic mass
* K, L, M, and N absorption edges
* Characteristic line energies
* Fluorescence yields and beta/alpha ratios

For the original data source, please cite:

Boone, J.M. and Chavez, A.E. (1996), Comparison of x-ray cross sections for
diagnostic and therapeutic medical physics. Med. Phys., 23: 1997-2005.
https://doi.org/10.1118/1.597899

## Installation

Install from PyPI:

```bash
python -m pip install mucoeff
```

Install from TestPyPI:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mucoeff
```

## Usage

```python
from mucoeff import mu, Flag

# Total mass attenuation coefficient for iron (Z = 26) at 100 keV.
value = mu(Flag.MU_TOT, Z=26, energy_keV=100.0)

# The same query can also be made with the original numerical flag.
value = mu(0, Z=26, energy_keV=100.0)

# Energy inputs can be scalar values, lists, or NumPy arrays.
values = mu(Flag.MU_TOT, Z=26, energy_keV=[10.0, 100.0, 1000.0])

# Element properties do not require an energy input.
density = mu(Flag.ELEMENT_DENSITY, Z=26)
```

## Inputs

The main entry point is:

```python
mu(flag, Z, energy_keV=None, on_error="nan")
```

* `flag`: either a `Flag` enum member, such as `Flag.MU_TOT`, or the
  corresponding integer flag, such as `0`
* `Z`: atomic number, from 1 to 100
* `energy_keV`: photon energy in keV; required for energy-dependent flags
  below 22, ignored for atomic data flags 22 and above
* `on_error`: behavior for out-of-range interpolation queries; use `"nan"`
  to return `NaN`, `"raise"` to raise an error, or a numeric fill value

## Units

* Photon energies are provided in keV.
* Cross sections and attenuation coefficients are returned in cm2/g.
* Density is returned in g/cm3.
* Atomic mass is returned in g/mol.
* Absorption edges and characteristic line energies are returned in keV.
* Fluorescence yields and beta/alpha ratios are unitless.

## Flag Reference

Flags can be passed either as `Flag.NAME` or as the corresponding integer.

| Integer | Enum name | Quantity                                          |
| ---: | --- |---------------------------------------------------|
| 0 | `Flag.MU_TOT` | Total mass attenuation coefficient                |
| 1 | `Flag.MU_PHOTO` | Photoelectric mass attenuation coefficient        |
| 2 | `Flag.MU_RAYLEIGH` | Rayleigh scattering coefficient                   |
| 3 | `Flag.MU_COMPTON` | Compton scattering coefficient                    |
| 4 | `Flag.MU_PAIR` | Pair production coefficient                       |
| 5 | `Flag.MU_TRIPLET` | Triplet production coefficient                    |
| 6 | - | Not used; returns `NaN`                           |
| 7 | - | Not used; returns `NaN`                           |
| 8 | `Flag.MU_TR_TOT` | Total mass energy-transfer coefficient            |
| 9 | `Flag.MU_TR_PHOTO` | Photoelectric energy-transfer coefficient         |
| 10 | `Flag.MU_TR_RAYLEIGH` | Rayleigh energy-transfer coefficient; returns zero |
| 11 | `Flag.MU_TR_COMPTON` | Compton energy-transfer coefficient               |
| 12 | `Flag.MU_TR_PAIR` | Pair-production energy-transfer coefficient       |
| 13 | `Flag.MU_TR_TRIPLET` | Triplet-production energy-transfer coefficient; returns zero |
| 14 | - | Not used; returns `NaN`                           |
| 15 | - | Not used; returns `NaN`                           |
| 16 | `Flag.MU_EN_TOT` | Total mass energy-absorption coefficient          |
| 17 | `Flag.MU_EN_PHOTO` | Photoelectric energy-absorption coefficient       |
| 18 | `Flag.MU_EN_RAYLEIGH` | Rayleigh energy-absorption coefficient; returns zero |
| 19 | `Flag.MU_EN_COMPTON` | Compton energy-absorption coefficient             |
| 20 | `Flag.MU_EN_PAIR` | Pair-production energy-absorption coefficient     |
| 21 | `Flag.MU_EN_TRIPLET` | Triplet-production energy-absorption coefficient; returns zero |
| 22 | `Flag.ELEMENT_DENSITY` | Element density                                   |
| 23 | `Flag.ATOMIC_MASS` | Atomic mass                                       |
| 24 | `Flag.K_EDGE` | K absorption edge                                 |
| 25 | `Flag.L1_EDGE` | L1 absorption edge                                |
| 26 | `Flag.L2_EDGE` | L2 absorption edge                                |
| 27 | `Flag.L3_EDGE` | L3 absorption edge                                |
| 28 | `Flag.M_EDGE` | M absorption edge                                 |
| 29 | `Flag.N_EDGE` | N absorption edge                                 |
| 30 | `Flag.KA1` | K-alpha 1 characteristic line energy              |
| 31 | `Flag.KA2` | K-alpha 2 characteristic line energy              |
| 32 | `Flag.KB1` | K-beta 1 characteristic line energy               |
| 33 | `Flag.KB2` | K-beta 2 characteristic line energy               |
| 34 | `Flag.LA1` | L-alpha 1 characteristic line energy              |
| 35 | `Flag.LA2` | L-alpha 2 characteristic line energy              |
| 36 | `Flag.LB1` | L-beta 1 characteristic line energy               |
| 37 | `Flag.KYIELD` | K-shell fluorescence yield                        |
| 38 | `Flag.LYIELD` | L-shell fluorescence yield                        |
| 39 | `Flag.BETA_ALPHA_RATIO` | Beta/alpha ratio                                  |

## Authors

Original C code by John M. Boone and Andres E. Chavez: https://doi.org/10.1118/1.597899

Python port by Gustavo Pacheco.

Contact: gustavo.pacheco@radboudumc.nl

## Version History

* 1.0.0
    * Initial Release

## License

The Python code is licensed under the MIT License. The bundled data are
redistributed under CC-BY 4.0. See `LICENSE` and `LICENSE-DATA` for details.

