pdfanalysis 0.1.0__tar.gz

pdfanalysis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Ratel-Ramond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdfanalysis-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: pdfanalysis
+Version: 0.1.0
+Summary: Automated PDF structure analysis for nanoparticles
+Home-page: https://github.com/nicoratel/pdfanalysis
+Author: Nicolas Ratel-Ramond
+Author-email: Nicolas Ratel-Ramond <nicolas.ratel-ramond@insa-toulouse.fr>
+License: MIT
+Project-URL: Homepage, https://github.com/nicoratel/pdfanalysis
+Project-URL: Repository, https://github.com/nicoratel/pdfanalysis.git
+Project-URL: Bug Tracker, https://github.com/nicoratel/pdfanalysis/issues
+Keywords: PDF,pair distribution function,nanoparticles,structure analysis,crystallography
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: ase>=3.22.0
+Requires-Dist: diffpy-cmi>=3.0.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: app
+Requires-Dist: streamlit>=1.20.0; extra == "app"
+Requires-Dist: plotly>=5.0.0; extra == "app"
+Provides-Extra: notebook
+Requires-Dist: ipython>=7.0.0; extra == "notebook"
+Requires-Dist: jupyter>=1.0.0; extra == "notebook"
+Requires-Dist: py3Dmol>=2.0.0; extra == "notebook"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Provides-Extra: all
+Requires-Dist: streamlit>=1.20.0; extra == "all"
+Requires-Dist: plotly>=5.0.0; extra == "all"
+Requires-Dist: ipython>=7.0.0; extra == "all"
+Requires-Dist: jupyter>=1.0.0; extra == "all"
+Requires-Dist: py3Dmol>=2.0.0; extra == "all"
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-cov>=3.0.0; extra == "all"
+Requires-Dist: black>=22.0.0; extra == "all"
+Requires-Dist: flake8>=4.0.0; extra == "all"
+Requires-Dist: mypy>=0.950; extra == "all"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PDFanalysis
+
+Automated PDF (Pair Distribution Function) structure analysis for small metallic nanoparticles.
+
+## Description
+
+PDFanalysis is a comprehensive Python package for analyzing nanoparticle structures using pair distribution function (PDF) analysis. It provides tools for:
+
+- **PDF extraction** from experimental data
+- **Structure generation** (icosahedra, decahedra, octahedra, spheres)
+- **Structure customization** (zoomscale, element substitution)
+- **PDF refinement** using diffpy.srfit
+- **Structure screening** against experimental PDFs
+- **Report generation** with detailed analysis results
+
+The recommended workflow for a single pdf is the following:
+- **Estimation of particle size** from experimental pdf data. Determines the r value at which the pdf signal is dominated by noise
+- **Structure generation**: icosahedra, octahedra, spheres and decahedra are generated with the size determined above (or specified by the user)
+- **Fast structure screening**: each structure is roughly refined against experimental data. Best results within a given confidence interval are considered for the fine refinement
+- **Fine strucutre screening**: structures who have passed the first refinement cycle are refined against experimental pdf. 
+
+
+## Installation
+
+### Install from PyPI (recommended)
+
+```bash
+pip install pdfanalysis
+```
+
+### Install with optional dependencies
+
+```bash
+# For Streamlit web app
+pip install pdfanalysis[app]
+
+# For Jupyter notebooks
+pip install pdfanalysis[notebook]
+
+# For development tools
+pip install pdfanalysis[dev]
+
+# Install everything
+pip install pdfanalysis[all]
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/nicoratel/pdfanalysis.git
+cd pdfanalysis
+pip install .
+```
+
+### Development installation (editable mode)
+
+```bash
+git clone https://github.com/nicoratel/pdfanalysis.git
+cd pdfanalysis
+pip install -e .
+```
+
+## Dependencies
+
+### Core dependencies
+- `numpy` - Numerical computations
+- `scipy` - Scientific computing and optimization
+- `matplotlib` - Plotting and visualization
+- `ase` - Atomic Simulation Environment
+- `diffpy-cmi` - DiffPy suite (structure manipulation + PDF refinement)
+- `tqdm` - Progress bars
+- `psutil` - CPU/memory management
+
+### Optional dependencies
+- `streamlit` - Web application framework
+- `plotly` - Interactive plots
+- `ipython` - Enhanced Python shell
+- `jupyter` - Notebook interface
+- `py3Dmol` - 3D molecular visualization
+
+## Quick Start
+
+### Using the main analysis function
+
+```python
+from pdfanalysis import perform_automatic_pdf_analysis
+
+results = perform_automatic_pdf_analysis(
+    pdf_file="path/to/data.gr",
+    cif_file="path/to/structure.cif",
+    r_coh=30.0,  # Coherence length in Angstroms
+    tolerance_size_structure=3.0,
+    n_spheres=2
+)
+```
+
+### Using individual classes
+
+```python
+from pdfanalysis import (
+    PDFExtractor,
+    StructureGenerator,
+    PDFRefinement,
+    StructureScreener
+)
+
+# Generate structures
+generator = StructureGenerator(
+    pdfpath="output_dir",
+    cif_file="structure.cif",
+    auto_mode=True,
+    pdf_file="data.gr"
+)
+strufile_dir = generator.run()
+
+# Screen structures
+screener = StructureScreener(
+    strufile_dir=strufile_dir,
+    pdffile_dir="pdf_directory",
+    fast_screening=True
+)
+best_results, candidates = screener.run()
+
+# Refine best structure
+refinement = PDFRefinement(
+    pdffile="data.gr",
+    strufile=best_results["data.gr"]["strufile"],
+    save_tag=True
+)
+rw = refinement.refine()
+```
+
+### Running the Streamlit app
+
+After installing with the `app` extras:
+
+```bash
+streamlit run app_pdf_analysis.py
+```
+
+## Package Structure
+
+```
+app_pdf_analysis.py             # Streamlit web interface
+pdfanalysis/
+├── __init__.py                      # Package initialization
+├── pdf_extractor.py                 # PDF extraction from experimental data
+├── structure_generator.py           # Nanoparticle structure generation
+├── structure_custom.py              # Structure transformation
+├── structure_report_generator.py    # PDF report generation
+├── pdf_refinement.py               # Full PDF refinement
+├── pdf_refinement_fast.py          # Fast refinement for screening
+├── structure_screener.py           # Structure screening
+├── pdfanalysis.py                  # Main analysis workflow
+```
+
+## Features
+
+### Automatic Structure Generation
+- Auto-detection of coherence length from PDF
+- Multiple structure types: icosahedra, decahedra, octahedra, spheres
+- Parallel processing for fast generation
+- Automatic filtering based on size range
+
+### Fast Screening
+- Two-pass screening: fast initial screening + full refinement
+- Automatic candidate selection (min(Rw) ± threshold%)
+- Progress tracking with tqdm
+- Multiprocessing support
+
+### Comprehensive Reports
+- PDF reports with fit curves, structure thumbnails
+- Top N results tables
+- 3D structure visualizations
+- Complete refinement statistics
+
+## Examples
+
+See the `examples/` directory for Jupyter notebooks demonstrating:
+- Basic PDF analysis workflow
+- Custom structure generation
+- Advanced refinement options
+- Batch processing
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```
+@software{pdfanalysis,
+  author = {Ratel-Ramond, Nicolas},
+  title = {PDFanalysis: Automated PDF structure analysis for nanoparticles},
+  year = {2026},
+  url = {https://github.com/nicoratel/pdfanalysis}
+}
+```
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Support
+
+For bugs and feature requests, please open an issue on GitHub:
+https://github.com/nicoratel/pdfanalysis/issues
+
+## Acknowledgments
+
+This package uses:
+- DiffPy-CMI for PDF refinement
+- ASE for structure manipulation
+- The Scientific Python ecosystem (NumPy, SciPy, Matplotlib)

pdfanalysis-0.1.0/README.md

@@ -0,0 +1,221 @@
+# PDFanalysis
+
+Automated PDF (Pair Distribution Function) structure analysis for small metallic nanoparticles.
+
+## Description
+
+PDFanalysis is a comprehensive Python package for analyzing nanoparticle structures using pair distribution function (PDF) analysis. It provides tools for:
+
+- **PDF extraction** from experimental data
+- **Structure generation** (icosahedra, decahedra, octahedra, spheres)
+- **Structure customization** (zoomscale, element substitution)
+- **PDF refinement** using diffpy.srfit
+- **Structure screening** against experimental PDFs
+- **Report generation** with detailed analysis results
+
+The recommended workflow for a single pdf is the following:
+- **Estimation of particle size** from experimental pdf data. Determines the r value at which the pdf signal is dominated by noise
+- **Structure generation**: icosahedra, octahedra, spheres and decahedra are generated with the size determined above (or specified by the user)
+- **Fast structure screening**: each structure is roughly refined against experimental data. Best results within a given confidence interval are considered for the fine refinement
+- **Fine strucutre screening**: structures who have passed the first refinement cycle are refined against experimental pdf. 
+
+
+## Installation
+
+### Install from PyPI (recommended)
+
+```bash
+pip install pdfanalysis
+```
+
+### Install with optional dependencies
+
+```bash
+# For Streamlit web app
+pip install pdfanalysis[app]
+
+# For Jupyter notebooks
+pip install pdfanalysis[notebook]
+
+# For development tools
+pip install pdfanalysis[dev]
+
+# Install everything
+pip install pdfanalysis[all]
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/nicoratel/pdfanalysis.git
+cd pdfanalysis
+pip install .
+```
+
+### Development installation (editable mode)
+
+```bash
+git clone https://github.com/nicoratel/pdfanalysis.git
+cd pdfanalysis
+pip install -e .
+```
+
+## Dependencies
+
+### Core dependencies
+- `numpy` - Numerical computations
+- `scipy` - Scientific computing and optimization
+- `matplotlib` - Plotting and visualization
+- `ase` - Atomic Simulation Environment
+- `diffpy-cmi` - DiffPy suite (structure manipulation + PDF refinement)
+- `tqdm` - Progress bars
+- `psutil` - CPU/memory management
+
+### Optional dependencies
+- `streamlit` - Web application framework
+- `plotly` - Interactive plots
+- `ipython` - Enhanced Python shell
+- `jupyter` - Notebook interface
+- `py3Dmol` - 3D molecular visualization
+
+## Quick Start
+
+### Using the main analysis function
+
+```python
+from pdfanalysis import perform_automatic_pdf_analysis
+
+results = perform_automatic_pdf_analysis(
+    pdf_file="path/to/data.gr",
+    cif_file="path/to/structure.cif",
+    r_coh=30.0,  # Coherence length in Angstroms
+    tolerance_size_structure=3.0,
+    n_spheres=2
+)
+```
+
+### Using individual classes
+
+```python
+from pdfanalysis import (
+    PDFExtractor,
+    StructureGenerator,
+    PDFRefinement,
+    StructureScreener
+)
+
+# Generate structures
+generator = StructureGenerator(
+    pdfpath="output_dir",
+    cif_file="structure.cif",
+    auto_mode=True,
+    pdf_file="data.gr"
+)
+strufile_dir = generator.run()
+
+# Screen structures
+screener = StructureScreener(
+    strufile_dir=strufile_dir,
+    pdffile_dir="pdf_directory",
+    fast_screening=True
+)
+best_results, candidates = screener.run()
+
+# Refine best structure
+refinement = PDFRefinement(
+    pdffile="data.gr",
+    strufile=best_results["data.gr"]["strufile"],
+    save_tag=True
+)
+rw = refinement.refine()
+```
+
+### Running the Streamlit app
+
+After installing with the `app` extras:
+
+```bash
+streamlit run app_pdf_analysis.py
+```
+
+## Package Structure
+
+```
+app_pdf_analysis.py             # Streamlit web interface
+pdfanalysis/
+├── __init__.py                      # Package initialization
+├── pdf_extractor.py                 # PDF extraction from experimental data
+├── structure_generator.py           # Nanoparticle structure generation
+├── structure_custom.py              # Structure transformation
+├── structure_report_generator.py    # PDF report generation
+├── pdf_refinement.py               # Full PDF refinement
+├── pdf_refinement_fast.py          # Fast refinement for screening
+├── structure_screener.py           # Structure screening
+├── pdfanalysis.py                  # Main analysis workflow
+```
+
+## Features
+
+### Automatic Structure Generation
+- Auto-detection of coherence length from PDF
+- Multiple structure types: icosahedra, decahedra, octahedra, spheres
+- Parallel processing for fast generation
+- Automatic filtering based on size range
+
+### Fast Screening
+- Two-pass screening: fast initial screening + full refinement
+- Automatic candidate selection (min(Rw) ± threshold%)
+- Progress tracking with tqdm
+- Multiprocessing support
+
+### Comprehensive Reports
+- PDF reports with fit curves, structure thumbnails
+- Top N results tables
+- 3D structure visualizations
+- Complete refinement statistics
+
+## Examples
+
+See the `examples/` directory for Jupyter notebooks demonstrating:
+- Basic PDF analysis workflow
+- Custom structure generation
+- Advanced refinement options
+- Batch processing
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```
+@software{pdfanalysis,
+  author = {Ratel-Ramond, Nicolas},
+  title = {PDFanalysis: Automated PDF structure analysis for nanoparticles},
+  year = {2026},
+  url = {https://github.com/nicoratel/pdfanalysis}
+}
+```
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Support
+
+For bugs and feature requests, please open an issue on GitHub:
+https://github.com/nicoratel/pdfanalysis/issues
+
+## Acknowledgments
+
+This package uses:
+- DiffPy-CMI for PDF refinement
+- ASE for structure manipulation
+- The Scientific Python ecosystem (NumPy, SciPy, Matplotlib)

pdfanalysis-0.1.0/pdfanalysis/__init__.py

@@ -0,0 +1,33 @@
+"""
+PDFanalysis package for automated PDF structure analysis.
+
+This package provides tools for:
+- PDF extraction from experimental data
+- Structure generation (nanoparticles)
+- Structure customization
+- PDF refinement
+- Structure screening
+- Report generation
+"""
+
+from .pdf_extractor import PDFExtractor
+from .structure_generator import StructureGenerator
+from .structure_custom import StructureCustom
+from .structure_report_generator import StructureReportGenerator
+from .pdf_refinement import PDFRefinement
+from .pdf_refinement_fast import PDFRefinementFast
+from .structure_screener import StructureScreener
+from .pdfanalysis import perform_automatic_pdf_analysis
+
+__all__ = [
+    'PDFExtractor',
+    'StructureGenerator',
+    'StructureCustom',
+    'StructureReportGenerator',
+    'PDFRefinement',
+    'PDFRefinementFast',
+    'StructureScreener',
+    'perform_automatic_pdf_analysis',
+]
+
+__version__ = '1.0.0'

pdfanalysis-0.1.0/pdfanalysis/pdf_extractor.py

@@ -0,0 +1,106 @@
+"""
+PDF Extractor module for extracting PDFs from experimental data.
+"""
+import subprocess
+import os
+import numpy as np
+from matplotlib import pyplot as plt
+
+
+class PDFExtractor:
+    def __init__(self,
+                 datafilelist,
+                 composition, 
+                 qmin,
+                 qmax,
+                 qmaxinst,
+                 wavelength=0.7107,
+                 dataformat='QA',
+                 rmin=0,
+                 rmax=50,
+                 rstep=0.01,
+                 bgscale=1,
+                 rpoly=0.9,
+                 emptyfile=None):
+        self.datafilelist=datafilelist
+        self.emptyfile=emptyfile
+        self.composition=composition
+        self.qmin=qmin
+        self.qmax=qmax
+        self.qmaxinst=qmaxinst
+        self.wl=wavelength
+        self.dataformat=dataformat
+        self.rmin=rmin
+        self.rmax=rmax
+        self.rstep=rstep
+        self.bgscale=bgscale
+        self.rpoly=rpoly
+
+
+    def writecfg(self):
+        """
+        datafilelist: list of paths to data files from wich PDF should be extracted
+        """
+
+        self.datapath=os.path.dirname(self.datafilelist[0])
+        self.pdfpath=self.datapath+'/extracted_PDF'
+        
+        os.makedirs(self.pdfpath,exist_ok=True)
+
+        cfg=open(self.pdfpath+'/pdfgetX3_GUI.cfg','w')
+        cfg.write('[DEFAULT] \n')
+        cfg.write('dataformat = %s' %self.dataformat +' \n')
+        
+        
+        
+        cfg.write('inputfile='+''.join(os.path.basename(i) +'\n' +'\t'
+                                for i in self.datafilelist[:-1]))
+        cfg.write('\t %s' %os.path.basename(self.datafilelist[-1])+'\n')
+        cfg.write('datapath = %s' % os.path.dirname(self.datafilelist[0])+'/' +'\n')
+        if self.emptyfile is not None:
+            cfg.write('\t %s' %os.path.dirname(self.emptyfile)+'\n')
+
+            cfg.write('bgscale=%f \n' %self.bgscale)
+            cfg.write('backgroundfile=%s' % os.path.basename(self.emptyfile)+'\n')
+        
+            
+        cfg.write('composition= %s \n'%str(self.composition))
+        cfg.write('qmin=%f \n' %self.qmin)
+        cfg.write('qmax=%f \n' %self.qmax)
+        cfg.write('qmaxinst=%f \n' %self.qmaxinst)
+        cfg.write('wavelength=%f \n' %self.wl)
+        cfg.write('mode = xray \n')
+        cfg.write('rpoly=%f \n' %self.rpoly)
+        cfg.write('rmin=%f \n' %self.rmin)
+        cfg.write('rstep=%f \n' %self.rstep)
+        cfg.write('rmax=%f \n' %self.rmax)       
+        cfg.write('output=%s' %self.pdfpath +'/@b.@o \n')
+        cfg.write('outputtype = sq,gr \n')
+        #cfg.write('plot = iq,fq,gr \n' )
+        cfg.write('force = yes \n')
+        
+        cfg.close()
+        return
+    
+
+    def extractpdf(self):
+        self.writecfg()
+        command = 'conda run -n py36 pdfgetx3 -c' +self.pdfpath+'/pdfgetX3_GUI.cfg'
+
+        # Use subprocess to execute the command
+        subprocess.run(command, shell=True)
+        print(f'PDF file(s) extracted in {self.pdfpath}')
+        # Plot pdf
+        
+        fig,ax=plt.subplots()
+        for file in self.datafilelist:
+            rootname=(os.path.basename(file).split('/')[-1]).split('.')[0]
+            pdffile=self.pdfpath+f'/{rootname}.gr'
+            r,g=np.loadtxt(pdffile,skiprows=27,unpack=True)
+            ax.plot(r,g,label=rootname)
+        ax.set_xlabel('r ($\\AA$)')
+        ax.set_ylabel('G(r)')
+        fig.legend()
+        fig.tight_layout()
+
+        return self.pdfpath