RIETPY

RIETPY is a Python library designed to automate Rietveld analysis using the RIETAN-FP engine. It streamlines the refinement process by providing tools to programmatically manipulate input files, execute the refinement engine, parse results, and visualize outputs.

Features

• Automated Execution: Run RIETAN-FP (rietan) and cif2ins directly from Python.
• Input Manipulation: Read, parse, and modify .ins files programmatically.
• Result Parsing: Extract R-factors ($R_{wp}$, $R_p$, $S$, etc.), refined lattice parameters, and all refined parameters from output files.
• Batch Analysis:
  • CSV-based: Run analysis on multiple samples with parameters defined in a CSV file.
  • Sequential Refinement: Automatically refine a series of datasets (e.g., temperature dependence), passing refined lattice parameters from one run to the next.
• Visualization: Plot observed vs. calculated diffraction patterns (.gpd files).
• Preprocessing: Convert data formats (xy to GENERAL), find sequential datasets, and create minimum background profiles.

Prerequisites

• OS: Windows
• Python: >= 3.13
• RIETAN-FP: The latest version of RIETAN-FP must be installed. It should be located at C:\Program Files\RIETAN_VENUS (default) or the executables (rietan, cif2ins) must be accessible in your system's PATH.

Installation

You can install RIETPY directly from PyPI:

pip install rietpy

Usage

1. Basic Execution

from rietpy.engine import RietanEngine

# Initialize engine (assumes 'rietan' is in PATH)
engine = RietanEngine()

# Run cif2ins (Create .ins from .cif)
engine.run_cif2ins("sample.cif", "template.ins")

# Run refinement
engine.run("sample.ins")

2. Parsing Results

from rietpy.parser import ResultParser

# Parse R-factors and all refined parameters
results = ResultParser.parse_lst("path/to/sample.lst")
print(f"Rwp: {results['Rwp']}, S: {results['S']}")
print(f"Scale: {results['SCALE']}, BKGD_0: {results['BKGD_0']}")

# Parse Lattice Parameters
lattice = ResultParser.parse_lattice_params("path/to/sample.lst")
print(f"Refined a: {lattice['a']}, c: {lattice['c']}")

3. Modifying Input Files

from rietpy.parser import InsParser

# Initialize with optional file path and conditional evaluation
parser = InsParser("sample.ins", evaluate_conditionals=True)

# Change a parameter
parser.set_param("NBEAM", "1")  # Set to Conventional X-ray

# Update lattice parameters
parser.set_lattice_params({'a': 5.123, 'c': 13.45})

# Update scale factor
parser.set_scale(1.234)

# Read and modify linear constraints
constraints = parser.read_linear_constraints()
parser.set_linear_constraints(["new_constraint_1", "new_constraint_2"])

parser.write("modified.ins")

4. Multi-step Refinement (Single Sample)

Run a multi-step refinement on a single dataset by defining a strategy in a CSV file. This allows you to gradually turn on parameters (e.g., Scale -> Background -> Lattice -> Profile -> Structure).

from rietpy.analysis import BatchAnalyzer

analyzer = BatchAnalyzer()

# 1. Generate a template CSV from an .ins file
# This creates a CSV with columns for all parameters found in the .ins file
analyzer.generate_template_csv("sample.ins", "strategy.csv")

# 2. Edit the CSV file to define steps (rows)
# Set '1' to refine a parameter, '0' to fix it.
# Each row represents one run of RIETAN.

# 3. Run the multi-step refinement
# Set real_time_plot=True to visualize Rwp and profile fitting progress in Jupyter Notebook
# Use resume_from_run to resume from a specific run number
analyzer.run_single_refinement("sample.ins", "strategy.csv", real_time_plot=True)
# analyzer.run_single_refinement("sample.ins", "strategy.csv", resume_from_run=3)

5. Sequential Refinement

Perform sequential refinement on a series of data files (e.g., temperature dependence). The refined parameters from one run are automatically propagated to the next.

Features:

• Anchor Points: Specify a list of .ins files in anchor_ins_files. If a file matches the current data file name, it resets the model (e.g., at a phase transition).
• Background Propagation: Support for .bkg files via anchor_bkg_files. Backgrounds are propagated or reset similar to .ins files.
• Multi-step Refinement: Use parameter_csv_files to define a multi-step refinement strategy (e.g., Step 1: Scale/Bkg, Step 2: +Lattice, Step 3: +Atomic Coords) for each anchor.
• Resume Capability: Resume analysis from a specific sample using resume_from.

from rietpy.analysis import BatchAnalyzer

analyzer = BatchAnalyzer()

# 1. Generate a template CSV for multi-step refinement (optional)
# analyzer.generate_template_csv("temp_100K.ins", "refinement_strategy.csv")

data_files = ["data/temp_100K.int", "data/temp_200K.int", "data/temp_300K.int"]

# List of available anchor .ins files.
# The analyzer matches them to data files by filename.
# e.g. "temp_100K.ins" is used for "temp_100K.int".
# If no anchor is found, the result from the previous run is used.
anchor_ins_files = ["anchors/temp_100K.ins", "anchors/temp_300K.ins"]

# Optional: CSV files for multi-step refinement strategies
parameter_csv_files = ["anchors/strategy_A.csv"]

# Optional: Background files (.bkg) can also be anchored/propagated
anchor_bkg_files = ["anchors/temp_100K.bkg"]

analyzer.run_sequential(
    data_files=data_files,
    anchor_ins_files=anchor_ins_files,
    parameter_csv_files=parameter_csv_files,
    anchor_bkg_files=anchor_bkg_files,
    output_dir="results_sequential",
    resume_from="temp_200K"  # Optional: Resume from a specific sample
)

6. Multi-phase Model Creation

Combine multiple single-phase .ins files into a single multi-phase .ins file.

from rietpy.engine import RietanEngine

engine = RietanEngine()

# Base file (Phase 1) + List of other phases
engine.combine_ins_files(
    base_ins="phase1.ins", 
    other_ins_list=["phase2.ins", "phase3.ins"], 
    output_ins="multiphase.ins"
)

7. Visualization

from rietpy.plot import Plotter

plotter = Plotter()
plotter.plot_pattern("sample.gpd", title="Refinement Result")

8. Preprocessing

from rietpy.preprocess import xy_to_general, get_sequential_dataset, create_minimum_background_profile

# Convert xy format to RIETAN GENERAL format
xy_to_general("data.xy", "data.int")

# Find sequential data files matching a pattern ('?' as wildcard)
data_files = get_sequential_dataset("data_dir", "sample_?.int")
# e.g., matches sample_0.int, sample_01.int, ...

# Create minimum background profile from multiple data files
create_minimum_background_profile(
    input_files=["data_1.int", "data_2.int", "data_3.int"],
    output_file="minimum_background.bkg"
)

9. Parsing Sequential Results

from rietpy.parser import ResultParser

# Parse results from a sequential run directory
# Returns a dict: {'Filename': [...], 'Rwp': [...], 'a': [...], ...}
seq_results = ResultParser.parse_sequential_results("results_sequential")

Project Structure

src/rietpy/
├── __init__.py     # Package exports (RietanEngine, InsParser, ResultParser, BatchAnalyzer)
├── constants.py    # Configuration constants and regex patterns
├── engine.py       # Wrappers for RIETAN-FP executables
├── parser.py       # Parsers for .ins (input) and .lst (output) files
├── analysis.py     # High-level automation (Batch, Sequential)
├── plot.py         # Visualization tools
└── preprocess.py   # Data format conversion and preprocessing utilities

License

MIT License