Getting Started

To begin using the Orochi framework, follow these steps to install the primary orochi meta-package and learn how to run the interactive tutorials.

### Installation

The preferred method is to use Miniconda Python and install from the “conda-forge” channel of Conda packages.

To add “conda-forge” to the conda channels, run the following in a terminal:

conda config --add channels conda-forge

We want to install our packages in a suitable conda environment. The following creates and activates a new environment named orochi_env:

conda create -n orochi_env orochi
conda activate orochi_env

To confirm that the installation was successful, type:

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

The output should print the latest version displayed on the badges above.

If the above does not work, you can use pip to download and install the latest release from the Python Package Index. To install using pip into your orochi_env environment, type:

pip install orochi-suite

— Installing Individual Packages

Sub-packages can also be installed individually using pip:

pip install orochi.base orochi.pixia orochi.pdfget orochi.phase orochi.pdfsim orochi.fit orochi.ui orochi.pipeline orochi.tutorial orochi.view

—

If you prefer to install from local source trees, clone the repositories and run the following in development mode:

pip install -e ./orochi.base -e ./orochi.pixia -e ./orochi.pdfget -e ./orochi.phase -e ./orochi.pdfsim -e ./orochi.fit -e ./orochi.ui -e ./orochi.pipeline -e ./orochi.tutorial -e ./orochi.view

### Running Tutorials

Official, self-contained tutorials reproducing the scientific results, figures, and benchmark refinements of the Orochi publication are provided in the orochi.tutorial package (https://github.com/Tominaka-Laboratory/orochi.tutorial).

To run any tutorial in headless command-line (CUI) mode:

python tutorials/00_ni_synchrotron_benchmark/run_tutorial.py
python tutorials/01_ceo2_reduction_and_qdepend/run_tutorial.py
python tutorials/02_ceo2_nanoparticle_explicit_vs_analytical/run_tutorial.py
python tutorials/03_pto2_nanosheet_2d_pbc/run_tutorial.py

To launch interactive Gradio web interfaces with 3D structure visualization and live parameter tuning:

python tutorials/00_ni_synchrotron_benchmark/run_tutorial.py --gui
python tutorials/01_ceo2_reduction_and_qdepend/run_tutorial.py --gui
python tutorials/02_ceo2_nanoparticle_explicit_vs_analytical/run_tutorial.py --gui
python tutorials/03_pto2_nanosheet_2d_pbc/run_tutorial.py --gui

For more detailed information and tutorials, please consult our online documentation <https://Tominaka-Laboratory.github.io/orochi>.

Origins and Philosophy

The creation of Orochi is rooted in a deep respect for the pioneering scientific foundations established over more than a century of X-ray physics and crystallography. In many ways, this work represents a deliberate re-examination and modern reconstruction of classical crystallographic principles, redesigned from the ground up to accelerate advanced materials discovery.

The author was first welcomed into the fascinating world of structural analysis through the inspiring guidance of Prof. Anthony K. Cheetham (University of Cambridge) around the 2012 centenary of Bragg’s discovery of X-ray diffraction. Learning from foundational texts and software by Prof. Simon J. L. Billinge and other pioneers, the author set out to study over 100 years of scattering physics and computational crystallographic implementations. Crucially, this journey involved systematically testing and re-evaluating the physical approximations and simplifications that had historically been adopted out of necessity due to the computational limits of earlier eras—such as angle-independent form factor approximations, enforced 3D periodic boundary conditions requiring artificial vacuum supercells, and bulk volume density baselines.

A pivotal turning point occurred in 2024 through personal discussions with Prof. Simon J. L. Billinge, which illuminated the pathway toward open, modular Python packaging for modern scientific computing.

License

Orochi and its official sub-packages are licensed under the GNU General Public License v3.0 (GPLv3). See LICENSE.rst for the full license text.

Academic Citation Policy

Orochi is developed as an academic open-source project. If you use Orochi in scientific research leading to a publication, presentation, or thesis, please support its ongoing development by citing our publication:

@article{tominaka2026orochi,
  title   = {Orochi: A Physics-Grounded Python Package for Pair Distribution Function Analysis of Crystalline and Low-Dimensional Materials},
  author  = {Tominaka, Satoshi},
  journal = {ChemRxiv},
  year    = {2026},
  url     = {https://chemrxiv.org/doc/d84591ff-85b9-489c-839a-4f7170dcc1c4}
}

For citations of individual sub-packages (e.g., orochi.base, orochi.pixia, orochi.pdfget), please refer to their respective repositories.

Support and Contribute

The Orochi project welcomes your expertise and enthusiasm!

If you see a bug or want to request a feature, please report it as an issue and/or submit a fix as a PR.

Feel free to fork the project and contribute. Improvements and fixes are always appreciated.

Before contributing, please read our Code of Conduct.

Contact

For more information on the Orochi framework, please visit the project web-page or email Dr. Satoshi Tominaka at tominaka.satoshi@nims.go.jp.