pdfanalysis 0.1.5

Automated PDF structure analysis for nanoparticles

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)

pip install pdfanalysis

This installs the complete package including the Streamlit web interface.

Install with optional dependencies

# For Jupyter notebooks with 3D visualization
pip install pdfanalysis[notebook]

# For development tools
pip install pdfanalysis[dev]

# Install everything
pip install pdfanalysis[all]

Install from source

git clone https://github.com/nicoratel/pdfanalysis.git
cd pdfanalysis
pip install .

Development installation (editable mode)

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

Running the Streamlit app

After installation, launch the web interface with:

pdfanalysis-app

This will automatically start the Streamlit server and open the app in your default browser.

Using the main analysis function

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

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()

Package Structure

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
└── app_pdf_analysis.py             # Streamlit web interface

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)