Overview

The orochi.pdfsim package is a Python module dedicated to the calculation of Pair Distribution Functions (PDFs), denoted as G(r). It interfaces with orochi.phase to obtain structural information and computes the PDF considering periodic boundary conditions.

The core calculations are optimized for speed using Numpy and Numba. While primarily designed for CPU-based computation, GPU support for large-scale calculations is under development to further enhance performance.

A key characteristic of orochi.pdfsim is its ability to incorporate the scattering angle dependence (Q-dependence) of atomic scattering factors. This feature is particularly advantageous for accurately simulating PDFs of materials containing pairs of atoms with significantly different atomic numbers.

Key Features

• Pair Distribution Function (PDF) Simulation:

  Calculates G(r) from structural models.

• Integration with ``orochi.phase``:

  Seamlessly retrieves atomic coordinates, occupancies, displacement parameters, and lattice information.

• Periodic Boundary Conditions:

  Correctly handles periodic structures to accurately compute pair distances across unit cell boundaries.

• High-Performance Core:

  Utilizes Numpy and Numba for efficient computation on CPUs.

• GPU Acceleration (Upcoming):

  GPU support is currently being updated to enable faster processing of large-scale simulations.

• Q-dependent Scattering Factors:

  Allows for the inclusion of the Q-dependence of atomic scattering factors, providing more accurate PDF simulations, especially for systems with heavy and light element combinations.

Quickstart: Simulating G(r)

from orochi.phase import Phase
from orochi.pdfsim import Simulator
import matplotlib.pyplot as plt

# 1. Load crystallographic structure
phase = Phase()
phase.read_file("CeO2.cif")
phase["shape_type"] = "analytical"   # Bulk crystal representation

# 2. Configure Simulator and link Phase
sim = Simulator()
sim.phase = phase
sim["rambda"] = 0.18033              # X-ray wavelength in Angstrom
sim["qmin"] = 1.0
sim["qmax"] = 25.0
sim["rmin"] = 1.5
sim["rmax"] = 30.0
sim["qdamp"] = 0.028                 # Instrumental resolution damping
sim["qdepend"] = True                # Exact Q-dependent form factors via DCT

# 3. Execution
# Standard call utilizes internal caching (only recalculates modified dependencies):
sim()

# Alternatively, use run(force=True) to guarantee full recalculation:
# sim.run(force=True)

# 4. Access calculated PDF arrays
r = sim.r
gr = sim.Gr

plt.plot(r, gr, label="Calculated G(r)")
plt.xlabel("r (Å)")
plt.ylabel("G(r) (Å⁻²)")
plt.legend()
plt.show()

Execution and Caching Lifecycle

orochi.pdfsim inherits from orochi.base.core.OrochiBase and incorporates dependency-aware method wrapping:

• Initial Execution: On the first call (_state == "INIT"), the entire pipeline executes: atomic coordinate expansion, shape envelope convolution, atomic form factors, pair histograms g_ij(r), and G(r) synthesis. Upon completion, state transitions to "DONE".

• Intelligent Incremental Recalculation (``sim()``): During optimization (e.g. refining scale factor or resolution damping Q_damp), expensive pair distance calculations (calc_rij) are automatically skipped because geometric parameters have not changed.

• Forced Recalculation (``sim.run(force=True)``): When parameters are modified outside standard dictionaries or when absolute state reset is desired, passing force=True resets internal states to "INIT", enforcing complete end-to-end recomputation.

pip install orochi.pdfsim

python -c "import orochi.pdfsim; print('Orochi PDFsim imported successfully')"

git clone https://github.com/Tominaka-Laboratory/orochi.pdfsim.git
cd orochi.pdfsim
pip install -e .

pip install -e .

@article{tominaka2026orochi,
  title   = {Orochi: A Physics-Grounded Python Package for Pair Distribution Function Analysis of Crystalline and Low-Dimensional Materials},
  author  = {Tominaka, Satoshi},
  year    = {2026},
  url     = {https://github.com/Tominaka-Laboratory/orochi}
}