multiel-spectra 0.1.0.0.5
Multi-Element Fluorescence Xray Spectra Generator
Requires Python: >=3.6
Keywords: xray, fluorescence, pypi, package

# Multiel_spectra

**Multi-element Spectra Generator**

Multiel_spectra is a Python package designed for simulating fluorescence X-ray spectra. It enables the simulation of photon transmission through multiple material layers generated by a source spectrum and incorporates detector effects.

## Name

Highly Scalable Multi-element Fluorescence X-ray Spectra Simulation.

## Description

Multiel_spectra is a package that approximates all steps in an X-ray Fluorescence measurement. It simulates the entire photon path, starting from the X-ray source to the detector, and accounts for transmission through various elemental layers. The primary objective of this package is to generate more accurate approximations of computer-simulated X-ray spectra to closely resemble real X-ray detected spectra. These generated spectra are valuable for various applications, including training artificial neural networks for tasks such as automatic element detection and denoising.


Multiel_spectra encompasses the following key elements in its simulation:

- **Incident Spectra (Source Spectra):** The incident spectra are simulated using the "spekpy" package, producing a tuple of arrays containing energy values (X) and spectrum fluence (Y). For detailed information, please refer to the "spekpy" documentation.

- **Fluorescence Spectra Transmission:** Multiel_spectra models elements in layers, requiring prior knowledge of the elemental composition of the probe. This composition is defined by the position of each element and its relative abundance within the probe. The fluorescence spectra generated by the source spectra are accurately transmitted through these different layers, with the option to remove the outermost layer (usually air). It's worth noting that only air has thickness, while the other layers are assumed to have a fixed thickness of 1 mm.

- **Detector Effects:** Multiel_spectra simulates various detector effects, including escape peaks, sum peaks, and detector efficiency.

## Approximations

Currently, Multiel_spectra makes certain approximations in its simulations:

**Source Spectra Transmission**: The current simulation assumes that the same source spectra arrives at all elements in different layers. It doesn't differentiate the source spectra for individual elements.

**Fluorescence Spectra Creation**: While SpectraGen accurately transmits different fluorescence spectra through various layers, it does not simulate the creation of new spectra using these transmitted fluorescence spectra as sources. This could be a potential enhancement for future versions.

**Photon Material Absorption**: SpectraGen approximates photon material absorption using perfect composited materials, without considering impurities or introducing noise. Exploring more realistic absorption models could be beneficial for increased accuracy. 


## Required Libraries 

Multiel_spectra relies on three main libraries:

Spekpy: A Python package used to simulate X-ray tube spectra, which serve as the incident spectra for generating X-ray fluorescence spectra.

Xraylarch: A Python package utilized to obtain mass attenuation coefficients for mixtures of compounds as a function of energy.

Scikit-beam: A Python package used to retrieve energies and cross sections for all X-ray lines in an element.

These libraries are integral to the functionality of Multiel_spectra. For further information you can refer to their documentation. 

## Installation

It is recommended to install and run the package in a virutal environment.

```python

pip install multiel_spectra

```

For Dataset generation torch is needed, hence the installation must be: 

```python

pip install multiel_spectra[torch]

```

### Setting the environment and related packages: 

Spekpy and Scikit-beam (skbeam) are not included in the requirements but are neccesary for the package. If already not installed in your system we recommend installation through the following: 

1. Locate the files necessary for the installation included in the package: 
(typically something like /opt/conda/lib/python3.10/site-packages/multiel_spectra)

```python

pip show multiel_spectra

```

<!-- As the package makes use of skbeam, a install_skbeam.py (and install_spekpy.py) script is included with the package so run: " python install_skbeam.py" in order to isntall it (link to the skbeam documentation for all the different installation procedures, this one is the reccomended one). This files are typically lcoated: /opt/conda/lib/python3.10/site-packages/multiel_spectra when you download it.  -->

2. set conda environment named 'base' 
3. run: "python <#introduce_multiel_package_location>/install_skbeam.py" in conda base environment.
4. run: "python <#introduce_multiel_package_location>/install spekpy.py" in conda base environment.
<!-- 4. install the rest of dependencies (only if neeeded)(torch, xraylarch, scipy..etc).   -->

The order is important since usually the packages created outside the conda environment will not be linked into the environment. 



<!-- Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. -->


link to official conda documentation: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html


## Usage


```python
#Generate the incident spectra
Prim, brem = ms.Primary_gen(30, 46, 0.1, "casim", "nist", 1, 9, "Mo", [('Be', 0.127), ('Air', 10)])
```

```python
#Compute a multiel-spectra with high number of counts and low noise
final_spectra, present_peaks, els_perc = ms.spectra_gen(np.array([38,25,13,0,8,7]), Prim, brem, s_counts = 30000,n_counts = 30000,b_counts = 1000, c_counts = 1000,  escape = True, sum = True, decal = True,  char_r = 15, brem_r = 15,noise_f = 1000 )
```
Output: 

![High count plot](./images/highcount.png)

The spectra is shown on blue, while on green are shown the elemental lines of the elements present on the spectra. Note that since spectra can be decalibrated the position of the peaks with respect the real energy position of the elemental lines may be displaced. 

```python
#Compute a multi-element spectra with low number of counts and high noise to signal ratio
final_spectra, present_peaks, els_perc = ms.spectra_gen(np.array([38,25,13,0,8,7]), Prim, brem, s_counts = 20,n_counts = 30,b_counts = 10, c_counts = 10,  escape = True, sum = True, decal = True, char_r = 1, brem_r = 1,noise_f = 1, prop = "" )
```
![low count plot](./images/lowcount.png)

Note that "Plot = True" by default and can be omitted, hence if a in interactive plot is not desired it must be explicitly be expressed in the input.

Interactive visualizations are provided trough Bokeh interface, but spectra histograms can be exported as arrays and used in other frameworks. 

(quizás poner un link a un google colab notebook donde haga todo)

## Support
fgarciaa@fi.infn.it

## Roadmap

* 3D photon path simulation 

* No approximation on transmission and excitation simulation 

* Material mix and impurities simulation

* ANN element detection 

* ANN denoising 

## Contributing

Contact the autor for contributions or suggestions. Open contributions will soon be available.

## Authors and acknowledgment

Thanks to the INFN-Firenze and Labec laboratory

- [INFN-Firenze](https://www.infn.it/)
- [Labec Laboratory](https://labec.fi.it/)

## License

MIT license. 

## Project status

**Note:** As of now, the project is in the final stages of developing the first working prototype. Development has been active and focused on achieving this milestone.

If you are interested in contributing to or maintaining this project, your involvement is welcome and highly appreciated. Whether you have ideas for improvements, want to help with documentation, or take on a more active role as a maintainer, your support can help ensure the project's continued success.

Feel free to reach out or submit pull requests if you'd like to get involved in shaping the future of this project.

Your update provides transparency about the project's current status and invites potential contributors or maintainers to participate in its development.