Quickstart: Real-Space PDF Refinement

The following example demonstrates refining the scale factor and atomic displacement parameter (U_iso) of a ceria (CeO₂) model against experimental Pair Distribution Function (G(r)) data:

import numpy as np
from orochi.phase import Phase
from orochi.pdfsim import Simulator
from orochi.fit import LeastSquaresOptimizer

# 1. Setup Phase and Simulator
phase = Phase()
phase.read_cif("CeO2.cif")

sim = Simulator()
sim.phase = phase
sim["qmax"] = 25.0
sim["qdamp"] = 0.04

# 2. Configure optimizable parameters and search bounds
sim["scale"] = 1.0
sim["scale", "min"] = 0.1
sim["scale", "max"] = 5.0
sim["scale", "fit"] = True

phase["uiso_0"] = 0.005
phase["uiso_0", "min"] = 0.0001
phase["uiso_0", "max"] = 0.05
phase["uiso_0", "fit"] = True

# 3. Configure Optimizer
opt = LeastSquaresOptimizer()
opt.simulators = [sim]
opt["fit_min"] = 1.5
opt["fit_max"] = 20.0
opt.study_name = "ceo2_refinement"

# Load experimental PDF data (r, G(r))
opt.read_file("CeO2_experimental.gr")

# 4. Execute Refinement
# Automated execution:
opt()

# Or explicit manual execution forcing clean re-evaluation:
# opt.run(force=True)

# 5. Inspect Results
print("Optimization Scores:", opt.best_scores)
print("Refined Parameters:", opt.best_params)

Execution Lifecycle & Force Recalculation

Like all core Orochi modules, LeastSquaresOptimizer and BayesOptimizer support dual execution interfaces:

• Automated execution via ``opt()``: Resets internal states and optimizes according to changed parameters.

• Manual execution via ``opt.run(force=True)``: Forcibly resets both the optimizer’s cache and all attached simulators’ caches (setting _state = "INIT"), guaranteeing a completely fresh evaluation from initial conditions.

Installation

Install via pip:

pip install orochi.fit

Or install in development mode from source:

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

To confirm successful installation:

python -c "import orochi.fit; print(orochi.fit.__version__)"

Citation

If you use orochi.fit in your research, please cite:

Orochi Software Suite, Tominaka Laboratory, National Institute for Materials Science (NIMS). https://github.com/Tominaka-Laboratory/orochi.fit

For Bayesian optimization workflows, please also cite Optuna:

Akiba et al., “Optuna: A Next-generation Hyperparameter Optimization Framework”, Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining (2019).

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE.rst file for details.

This copyleft license guarantees that Orochi remains freely accessible, open, and transparent to the entire scientific community, and that all derivative works must likewise remain open source.

Citation

If you use this package in academic research, please cite:

@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}
}

Contact

For bug reports and questions, visit GitHub Issues or contact Dr. Satoshi Tominaka at tominaka.satoshi@nims.go.jp.