phasesmith_workflows/
lib.rs

1//! Application-neutral native refinement and project workflows.
2//!
3//! This crate is the shared host boundary for Python adapters and future
4//! native application consumers. It contains no `PyO3`, Tauri, GUI, or
5//! file-format types.
6//! Applications normally use it through
7//! [`phasesmith::workflows`](https://docs.rs/phasesmith/latest/phasesmith/).
8//!
9//! # Workflow families
10//!
11//! - **Backgrounds:** differentiable Chebyshev, polynomial, point, amorphous,
12//!   and composite models.
13//! - **Le Bail:** intensity extraction with optional profile/lattice
14//!   refinement, covariance, checkpoints, and dynamic reflection domains.
15//! - **TOF Le Bail:** typed microsecond-domain fixed-instrument calculation and
16//!   nonnegative intensity extraction with fused d/instrument derivatives.
17//! - **Rietveld:** calculation, prepared objective products, structural and
18//!   general refinement, staged recipes, and joint multi-histogram refinement.
19//! - **Quantitative analysis:** validated Hill–Howard phase fractions.
20//! - **Infrastructure:** typed parameters, bounds, constraints, residuals,
21//!   cancellation, limits, events, clocks, diagnostics, and checkpoints.
22//!
23//! # Selecting the level
24//!
25//! Use `calculate_*` functions for a deterministic forward calculation. Use a
26//! `Prepared*Objective` when integrating a custom optimizer and consuming
27//! values/JVP/VJP products directly. Use `refine_*` for the built-in solver, and
28//! the corresponding `_with_runtime` variant when an application needs
29//! cancellation, progress events, or checkpoint sinks.
30//!
31//! [`LeBailInput`] and [`RietveldInput`] own validated observations and domain
32//! state. Result/checkpoint records and structured event diagnostics are the
33//! stable programmatic output; human-readable event messages should not be
34//! parsed.
35//!
36//! # Application integration
37//!
38//! Workflows are synchronous and application-neutral. A desktop or async host
39//! runs them on its chosen worker mechanism, connects
40//! [`RefinementRuntime`] to its cancellation/event bridge, and uses
41//! `phasesmith-persistence` for native project state. The `joint_pbso4` example
42//! in this package demonstrates a complete Rust-only X-ray/neutron refinement.
43//! The facade's
44//! [real-data walkthrough](https://docs.rs/phasesmith/latest/phasesmith/guide/real_data_rietveld/)
45//! explains that example step by step, and its
46//! [operations guide](https://docs.rs/phasesmith/latest/phasesmith/guide/refinement_operations/)
47//! covers staging, bounded runtimes, checkpoint continuation, and result
48//! acceptance.
49//! The facade provides collected mathematical references for
50//! [refinement](https://docs.rs/phasesmith/latest/phasesmith/guide/mathematics/refinement/)
51//! and
52//! [background models](https://docs.rs/phasesmith/latest/phasesmith/guide/mathematics/backgrounds/).
53
54mod backgrounds;
55mod constraints;
56mod lattice;
57mod lebail;
58mod parameters;
59mod phase_scale_estimation;
60mod profile_estimation;
61mod quantitative;
62mod residuals;
63mod rietveld;
64mod rietveld_general_objective;
65mod rietveld_general_parameters;
66mod rietveld_general_solver;
67mod rietveld_joint;
68mod rietveld_joint_solver;
69mod rietveld_objective;
70mod rietveld_parameters;
71mod rietveld_project;
72mod rietveld_recipe;
73mod rietveld_solver;
74mod runtime;
75mod sample_physics;
76mod tof_lebail;
77mod tof_multibank;
78mod tof_multibank_geometry;
79mod tof_multibank_instrument;
80mod tof_multibank_lattice;
81mod tof_multibank_project;
82mod tof_project;
83mod tof_structural_multibank;
84mod tof_structural_multibank_solver;
85mod tof_structural_project;
86
87pub use backgrounds::{
88    AmorphousBackground, AmorphousPeak, BackgroundBasis, BackgroundError, BackgroundModel,
89    ChebyshevBackground, CompositeBackground, DifferentiableBackground, PointBackground,
90    PolynomialBackground,
91};
92pub use constraints::{
93    AffineConstraint, Constraint, ConstraintDerivativeMatrix, ConstraintError, ConstraintTransform,
94    FixedConstraint, LinearConstraint, LinearTerm,
95};
96pub use lattice::{
97    CwLatticeGeometry, GeneratedLatticeDomain, LatticeBounds, LatticeError,
98    LatticeParameterization, LatticeReflectionDomain, TofLatticeGeometry, cw_lattice_geometry,
99    tof_lattice_geometry,
100};
101pub use lebail::{
102    CoincidentReflectionGroup, CovarianceMatrix, IntensityExtractionResult, LeBailCalculation,
103    LeBailCheckpoint, LeBailError, LeBailInput, LeBailIterationRecord, LeBailOptions, LeBailPhase,
104    LeBailResult, ParameterChange, PhasePatternComponent, ReflectionIntensity,
105    build_lebail_parameter_set, build_lebail_parameter_set_with_lattice, calculate_lebail_pattern,
106    calculate_lebail_pattern_with_background, extract_lebail_intensities,
107    initialize_lebail_intensities, iterate_lebail_once, lebail_background_parameter_key,
108    lebail_instrument_parameter_key, lebail_lattice_parameter_key, lebail_phase_scale_key,
109    lebail_reflection_position_key, refine_lebail, refine_lebail_with_runtime,
110};
111pub use parameters::{ParameterBounds, ParameterError, ParameterKey, ParameterSet, ParameterSpec};
112pub use phase_scale_estimation::{
113    PhaseScaleEstimationError, PhaseScaleEstimationResult, estimate_initial_phase_scales,
114};
115pub use profile_estimation::{
116    ProfileEstimationError, ProfileEstimationInput, ProfileEstimationMode,
117    ProfileEstimationOptions, ProfileEstimationResult, ProfileEstimationStage,
118    ProfileEstimationStageKind, estimate_effective_profile, starting_profile_from_fwhm,
119};
120pub use quantitative::{
121    PhaseWeightFraction, QuantitativeError, QuantitativePhase, QuantitativePhaseAnalysis,
122    quantitative_phase_analysis, quantitative_phase_analysis_with_covariance,
123};
124pub use residuals::{
125    ResidualError, ResidualEvaluation, ResidualOptions, evaluate_residuals, evaluate_tof_residuals,
126};
127pub use rietveld::{
128    RietveldCalculation, RietveldCalculationOptions, RietveldError, RietveldInput, RietveldPhase,
129    RietveldPhaseCalculation, RietveldTopologyChange, calculate_rietveld_pattern,
130};
131pub use rietveld_general_objective::{
132    DEFAULT_MAX_LINEARIZATION_ELEMENTS, PreparedGeneralFreeLinearization,
133    PreparedGeneralRietveldObjective, RietveldGeneralObjectiveError,
134};
135pub use rietveld_general_parameters::{
136    RietveldGeneralParameterError, RietveldInstrumentParameter, RietveldParameterLayout,
137    RietveldParameterSelection,
138};
139pub use rietveld_general_solver::{
140    RietveldCovarianceMatrix, RietveldCovarianceOptions, RietveldGeneralCheckpoint,
141    RietveldGeneralRefinementError, RietveldGeneralRefinementResult, RietveldParameterCorrelation,
142    refine_general_rietveld, refine_general_rietveld_with_runtime,
143};
144pub use rietveld_joint::{
145    JointRietveldError, JointRietveldGradient, JointRietveldHistogram, JointRietveldLayout,
146    JointRietveldProduct, PreparedJointRietveldObjective,
147};
148pub use rietveld_joint_solver::{
149    JointRietveldCheckpoint, JointRietveldIterationRecord, JointRietveldMetrics,
150    JointRietveldRefinementError, JointRietveldRefinementOptions, JointRietveldRefinementResult,
151    JointRietveldTopologyChange, refine_joint_rietveld, refine_joint_rietveld_with_runtime,
152};
153pub use rietveld_objective::{
154    PreparedRietveldLinearization, PreparedRietveldObjective, RietveldObjectiveError,
155};
156pub use rietveld_parameters::{
157    RietveldParameterError, RietveldStructuralLayout, RietveldStructuralSelection,
158    SiteCoordinateModel,
159};
160pub use rietveld_project::{RietveldAnalysis, RietveldProjectError, RietveldProjectState};
161pub use rietveld_recipe::{
162    RietveldRecipe, RietveldRecipeError, RietveldRecipeMode, RietveldRecipeSinks, RietveldStage,
163    RietveldStageResult, RietveldWorkflowResult, intelligent_rietveld_recipe, run_rietveld_recipe,
164    run_rietveld_recipe_with_sinks, validate_rietveld_recipe,
165};
166pub use rietveld_solver::{
167    RietveldCheckpoint, RietveldIterationRecord, RietveldRefinementError,
168    RietveldRefinementOptions, RietveldRefinementResult, refine_rietveld,
169    refine_rietveld_with_runtime,
170};
171pub use runtime::{
172    CancellationError, CancellationToken, CheckpointSink, DiagnosticValue, MonotonicClock,
173    RefinementEvent, RefinementEventKind, RefinementEventSink, RefinementLimits, RefinementRuntime,
174    RefinementStop, RuntimeClock, RuntimeError, TerminationReason,
175};
176pub use sample_physics::{
177    EvaluatedSamplePhysics, RietveldSamplePhysicsModel, SamplePhysicsError, SamplePhysicsParameter,
178};
179pub use tof_lebail::{
180    TofChebyshevBackground, TofChebyshevBasis, TofLeBailCalculation, TofLeBailCheckpoint,
181    TofLeBailError, TofLeBailInput, TofLeBailIterationRecord, TofLeBailOptions, TofLeBailPhase,
182    TofLeBailResult, TofReflectionIntensity, calculate_tof_lebail_pattern, refine_tof_lebail,
183    refine_tof_lebail_with_runtime,
184};
185pub use tof_multibank::{
186    TofLeBailBank, TofMultiBankCheckpoint, TofMultiBankCheckpointBank, TofMultiBankError,
187    TofMultiBankInput, TofMultiBankIterationRecord, TofMultiBankMetrics, TofMultiBankResult,
188    TofMultiBankResultBank, refine_tof_multibank, refine_tof_multibank_with_runtime,
189};
190pub use tof_multibank_geometry::{
191    TofGeometryCorrelation, TofGeometryDiagnostics, TofGeometryParameterKey,
192    TofMultiBankGeometryCheckpoint, TofMultiBankGeometryCheckpointBank, TofMultiBankGeometryError,
193    TofMultiBankGeometryInput, TofMultiBankGeometryIterationRecord, TofMultiBankGeometryOptions,
194    TofMultiBankGeometryResult, refine_tof_multibank_geometry,
195    refine_tof_multibank_geometry_with_runtime,
196};
197pub use tof_multibank_instrument::{
198    TofBankInstrumentModel, TofBankInstrumentState, TofInstrumentCorrelation,
199    TofInstrumentDiagnostics, TofInstrumentParameterBound, TofInstrumentParameterChange,
200    TofMultiBankInstrumentCheckpoint, TofMultiBankInstrumentCheckpointBank,
201    TofMultiBankInstrumentError, TofMultiBankInstrumentInput,
202    TofMultiBankInstrumentIterationRecord, TofMultiBankInstrumentOptions,
203    TofMultiBankInstrumentResult, refine_tof_multibank_instrument,
204    refine_tof_multibank_instrument_with_runtime,
205};
206pub use tof_multibank_lattice::{
207    TofLatticeParameterChange, TofMultiBankLatticeCheckpoint, TofMultiBankLatticeError,
208    TofMultiBankLatticeInput, TofMultiBankLatticeIterationRecord, TofMultiBankLatticeOptions,
209    TofMultiBankLatticeResult, TofSharedLatticePhase, TofSharedLatticeState,
210    refine_tof_multibank_lattice, refine_tof_multibank_lattice_with_runtime,
211};
212pub use tof_multibank_project::{
213    TofMultiBankGeometryAnalysis, TofMultiBankGeometryProjectState, TofMultiBankProjectError,
214};
215pub use tof_project::{TofLeBailAnalysis, TofLeBailProjectState, TofProjectError};
216pub use tof_structural_multibank::{
217    PreparedStructuralTofMultiBankObjective, StructuralTofBank, StructuralTofBankCalculation,
218    StructuralTofMultiBankCalculation, StructuralTofMultiBankError, StructuralTofMultiBankGradient,
219    StructuralTofMultiBankInput, StructuralTofMultiBankLayout, StructuralTofMultiBankProduct,
220};
221pub use tof_structural_multibank_solver::{
222    StructuralTofMultiBankCheckpoint, StructuralTofMultiBankIterationRecord,
223    StructuralTofMultiBankRefinementError, StructuralTofMultiBankRefinementOptions,
224    StructuralTofMultiBankRefinementResult, refine_structural_tof_multibank,
225    refine_structural_tof_multibank_with_runtime,
226};
227pub use tof_structural_project::{
228    StructuralTofMultiBankAnalysis, StructuralTofMultiBankProjectState, StructuralTofProjectError,
229};
phasesmith_workflows/lib.rs

phasesmith_workflows/
lib.rs
