Crate phasesmith 

PhaseSmith

PhaseSmith is a native Rust library for powder-diffraction profile calculation, crystallography, Le Bail extraction, Rietveld refinement, and versioned project persistence. This facade is the recommended dependency for applications. It exposes the focused implementation crates under one version without embedding Python, PyO3, a GUI toolkit, or a process runtime.

The Python distribution is a separate adapter over the same native kernels. A Rust program, including a Tauri desktop application, calls this crate directly and does not need a Python interpreter or sidecar.

Which API should I start with?

Task	Start here
Evaluate profiles or subtract a smooth background	core
Work with cells, symmetry, reflections, or scattering	crystallography
Compose crystal structures into calculated patterns	engine
Read powder data, CIFs, or space-group metadata	io
Own application-neutral patterns, phases, and projects	model
Run Le Bail, Rietveld, or quantitative workflows	workflows
Save native projects and write stable reports	persistence
Bound worker threads for application integration	execution

The guide module adds task-oriented explanations that span those crate boundaries:

• guide::getting_started contains small, runnable native examples;
• guide::architecture explains ownership and dependency direction;
• guide::scientific_conventions defines units, layouts, and derivatives;
• guide::mathematics documents the implemented equations and analytical chains;
• guide::workflows maps calculation and refinement entry points;
• guide::application_hosts covers desktop/GUI integration.

Quick start: calculate a profile

The lowest-level profile API borrows a strictly increasing grid and structure-of-arrays peak parameters. The result owns the calculated values and analytical derivatives.

use phasesmith::core::{
    GridView, PeakBatchView, SupportPolicy, accumulate_batch,
};

let x = (0..=1_000)
    .map(|index| 20.0 + f64::from(index) * 0.01)
    .collect::<Vec<_>>();
let positions = [24.0, 26.0];
let intensities = [100.0, 80.0];
let fwhms = [0.08, 0.10];
let etas = [0.30, 0.50];

let grid = GridView::new(&x)?;
let peaks = PeakBatchView::new(&positions, &intensities, &fwhms, &etas)?;
let result = accumulate_batch(
    grid,
    peaks,
    SupportPolicy::FwhmMultiple(20.0),
)?;

assert_eq!(result.y.len(), x.len());
assert_eq!(result.derivatives.local.peak_count(), 2);

For values without derivative storage, use core::accumulate_values_batch. Higher-level structural calculations and refinements build on the same kernels rather than reproducing their formulas.

Design promises

• Explicit units: public physical fields include unit suffixes where practical; see guide::scientific_conventions.
• Validated boundaries: borrowed numerical views and owned domain records validate shapes, finiteness, ordering, and resource limits.
• Analytical products: calculation APIs expose values, sparse/dense Jacobians, JVPs, and VJPs instead of relying on finite differences.
• Bounded execution: application hosts choose an execution::ExecutionPolicy rather than modifying Rayon’s global thread pool.
• Adapter independence: Python objects, Tauri handles, and persistence wire records do not enter the numerical or domain crates.

API status

PhaseSmith is pre-1.0. Scientific conventions and validated boundaries are intentional, but Rust type names and composition APIs may still evolve between minor releases. Commit Cargo.lock in applications and consult the versioned PhaseSmith documentation when upgrading.

Re-exports

pub use phasesmith_core as core;

pub use phasesmith_crystallography as crystallography;

pub use phasesmith_engine as engine;

pub use phasesmith_execution as execution;

pub use phasesmith_io as io;

pub use phasesmith_model as model;

pub use phasesmith_persistence as persistence;

pub use phasesmith_workflows as workflows;

Modules

guide

Task-oriented guides for native Rust consumers and application hosts.