Crate phasesmith_workflows

Expand description

Application-neutral native refinement and project workflows.

This crate is the shared host boundary for Python adapters and future native application consumers. It contains no PyO3, Tauri, GUI, or file-format types. Applications normally use it through phasesmith::workflows.

§Workflow families

Backgrounds: differentiable Chebyshev, polynomial, point, amorphous, and composite models.
Le Bail: intensity extraction with optional profile/lattice refinement, covariance, checkpoints, and dynamic reflection domains.
TOF Le Bail: typed microsecond-domain fixed-instrument calculation and nonnegative intensity extraction with fused d/instrument derivatives.
Rietveld: calculation, prepared objective products, structural and general refinement, staged recipes, and joint multi-histogram refinement.
Quantitative analysis: validated Hill–Howard phase fractions.
Infrastructure: typed parameters, bounds, constraints, residuals, cancellation, limits, events, clocks, diagnostics, and checkpoints.

§Selecting the level

Use calculate_* functions for a deterministic forward calculation. Use a Prepared*Objective when integrating a custom optimizer and consuming values/JVP/VJP products directly. Use refine_* for the built-in solver, and the corresponding _with_runtime variant when an application needs cancellation, progress events, or checkpoint sinks.

LeBailInput and RietveldInput own validated observations and domain state. Result/checkpoint records and structured event diagnostics are the stable programmatic output; human-readable event messages should not be parsed.

§Application integration

Workflows are synchronous and application-neutral. A desktop or async host runs them on its chosen worker mechanism, connects RefinementRuntime to its cancellation/event bridge, and uses phasesmith-persistence for native project state. The joint_pbso4 example in this package demonstrates a complete Rust-only X-ray/neutron refinement. The facade’s real-data walkthrough explains that example step by step, and its operations guide covers staging, bounded runtimes, checkpoint continuation, and result acceptance. The facade provides collected mathematical references for refinement and background models.

Structs§

AffineConstraint: Define target = multiplier * source + offset.
AmorphousBackground: Sum of broad area-normalized Gaussian amorphous components.
AmorphousPeak: One area-normalized broad Gaussian component in degrees 2theta.
BackgroundBasis: Row-major sample-by-parameter analytical background derivatives.
CancellationToken: Thread-safe first-request-wins cooperative cancellation token.
ChebyshevBackground: Chebyshev series on one explicit closed degree domain.
CoincidentReflectionGroup: Numerically coincident profile columns and their matrix rank.
CompositeBackground: Ordered additive composition of analytical models.
ConstraintDerivativeMatrix: Row-major derivative d physical values / d scaled free values.
ConstraintTransform: Validated ordered mapping between free solver coordinates and all values.
CovarianceMatrix: Square row-major covariance over scaled free parameters.
CwLatticeGeometry: CW reflection geometry and independent lattice derivatives.
EvaluatedSamplePhysics: Evaluated contribution arrays plus stable provider derivative names.
FixedConstraint: Set one target parameter to a constant during expansion.
GeneratedLatticeDomain: Generated guarded reflection arrays and topology-transfer diagnostics.
IntensityExtractionResult: One non-negative multiplicative redistribution result.
JointRietveldCheckpoint: Complete accepted state for deterministic joint continuation.
JointRietveldGradient: Complete accepted-state value and gradient of a joint objective.
JointRietveldHistogram: One experiment in a joint native Rietveld objective.
JointRietveldIterationRecord: One accepted joint Gauss–Newton iteration.
JointRietveldLayout: Stable shared/local parameter packing for a joint objective.
JointRietveldMetrics: Aggregate powder residual metrics over all joint histograms.
JointRietveldProduct: One histogram’s profile and directional derivative.
JointRietveldRefinementOptions: Numerical and bounded-runtime controls for a joint native refinement.
JointRietveldRefinementResult: Final accepted joint native refinement result.
JointRietveldTopologyChange: One topology change owned by a specific histogram.
LatticeBounds: Finite box bounds in one lattice parameterization.
LatticeParameterization: Independent physical lattice variables for one exact crystallographic setting.
LatticeReflectionDomain: Bounded monochromatic reflection topology with stable intensity transfer.
LeBailCalculation: Native fixed-phase pattern result used by extraction and adapters.
LeBailCheckpoint: Complete immutable continuation state for the fixed-reflection workflow.
LeBailInput: Observations, instrument, and ordered fixed-reflection phases.
LeBailIterationRecord: One immutable accepted fixed-reflection iteration.
LeBailOptions: Deterministic controls for fixed-reflection extraction.
LeBailPhase: One fixed reflection phase whose integrated intensities are extracted.
LeBailResult: Complete native fixed-reflection Le Bail result.
LinearConstraint: Define target = offset + sum(coefficient * source).
LinearTerm: One source/coefficient pair in a linear constraint.
MonotonicClock: Process-local monotonic clock backed by Instant.
ParameterBounds: Closed lower and upper scalar bounds.
ParameterChange: One accepted physical profile-parameter change.
ParameterKey: Stable structured identity for one refinable scalar.
ParameterSet: Deterministically ordered immutable scalar specifications.
ParameterSpec: Value, unit, scale, bounds, and selection for one scalar.
PhasePatternComponent: One display-ready phase curve.
PhaseScaleEstimationResult: Diagnostics and restart-ready input produced by phase-scale initialization.
PhaseWeightFraction: One normalized crystalline weight fraction.
PointBackground: Linear interpolation through fixed knots with refinable values.
PolynomialBackground: Power series on the normalized input-grid coordinate [-1, 1].
PreparedGeneralFreeLinearization: Complete weighted Jacobian in scaled free-parameter coordinates.
PreparedGeneralRietveldObjective: Reusable complete physical objective for one accepted native state.
PreparedJointRietveldObjective: Prepared matrix-free sum of all histogram objectives.
PreparedRietveldLinearization: One reusable parameter-major physical structural Jacobian and its values.
PreparedRietveldObjective: Reusable structural values and derivative products for one accepted state.
PreparedStructuralTofMultiBankObjective: Prepared matrix-free structural TOF sum over all banks.
ProfileEstimationInput: Validated input for one predominantly single-phase profile estimate.
ProfileEstimationOptions: Deterministic controls for staged effective-profile estimation.
ProfileEstimationResult: Final effective starting profile and the complete staged selection audit.
ProfileEstimationStage: Compact audit record for one attempted stage.
QuantitativePhase: Metadata required by the Hill–Howard scale relation.
QuantitativePhaseAnalysis: Weight fractions and their row-major covariance propagated from phase scales.
RefinementEvent: One immutable orchestration-boundary event.
RefinementLimits: Hard upper bounds independent of convergence criteria.
RefinementRuntime: Stateful method-independent refinement boundary guard.
RefinementStop: Normal cooperative/budget termination returned at a safe boundary.
ReflectionIntensity: Final stable reflection identity and intensity.
ResidualEvaluation: Full residual arrays and standard masked powder metrics.
ResidualOptions: Weighting and degrees-of-freedom controls for residual evaluation.
RietveldAnalysis: One complete runnable single-histogram native Rietveld analysis.
RietveldCalculation: Display-ready structural calculation and residual metrics.
RietveldCalculationOptions: Deterministic calculation controls shared by later native refinement.
RietveldCheckpoint: Complete accepted state for deterministic native continuation.
RietveldCovarianceMatrix: Square row-major covariance over the complete physical parameter order.
RietveldCovarianceOptions: Controls for the optional small parameter-space identifiability analysis.
RietveldGeneralCheckpoint: Complete accepted state for deterministic constrained continuation.
RietveldGeneralRefinementResult: Final complete native constrained-refinement result.
RietveldInput: Observations, experiment state, and ordered structural phases.
RietveldIterationRecord: One accepted native Rietveld Gauss–Newton iteration.
RietveldParameterCorrelation: One nearly collinear pair of scaled-free Jacobian columns.
RietveldParameterLayout: Ordered complete physical parameters and state transforms.
RietveldParameterSelection: Complete selected built-in parameter families for one native Rietveld run.
RietveldPhase: One owned monochromatic structural phase and its sample-physics inputs.
RietveldPhaseCalculation: One labeled phase contribution and its crystallographic intermediates.
RietveldProjectState: Revisioned native project plus zero or one runnable analysis per histogram.
RietveldRecipe: Auditable explicit or intelligent stage sequence.
RietveldRecipeSinks: Cloneable host observers shared across every stage runtime.
RietveldRefinementOptions: Numerical and bounded-runtime controls for native structural refinement.
RietveldRefinementResult: Final accepted native structural refinement result.
RietveldStage: One caller-visible active parameter set and acceptance policy.
RietveldStageResult: Auditable outcome from one attempted recipe stage.
RietveldStructuralLayout: Ordered physical parameters and exact transforms to/from engine layouts.
RietveldStructuralSelection: Structural parameter families selected for one native Rietveld layout.
RietveldTopologyChange: Reflection-topology change attached to an accepted structural step.
RietveldWorkflowResult: Complete or safely stopped native staged workflow.
SamplePhysicsParameter: One stable refinable built-in sample-physics scalar.
SiteCoordinateModel: Symmetry-allowed coordinate tangent basis for one asymmetric site.
StructuralTofBank: One observed bank and every bank-local structural-TOF quantity.
StructuralTofBankCalculation: One bank’s display-ready structural TOF calculation.
StructuralTofMultiBankAnalysis: One complete runnable structural multi-bank TOF analysis.
StructuralTofMultiBankCalculation: Ordered multi-bank structural TOF calculation.
StructuralTofMultiBankCheckpoint: Complete last-accepted state for deterministic continuation.
StructuralTofMultiBankGradient: Complete objective values and gradient in joint physical order.
StructuralTofMultiBankInput: Shared structural phase plus one or more explicit TOF banks.
StructuralTofMultiBankIterationRecord: One atomically accepted structural TOF step.
StructuralTofMultiBankLayout: Stable shared/local physical parameter packing for structural TOF banks.
StructuralTofMultiBankProduct: One bank’s profile and joint-parameter directional derivative.
StructuralTofMultiBankProjectState: Revisioned project plus disjoint structural multi-bank TOF analyses.
StructuralTofMultiBankRefinementOptions: Numerical and bounded-runtime controls for structural multi-bank TOF.
StructuralTofMultiBankRefinementResult: Final accepted structural TOF refinement state.
TofBankInstrumentModel: Selected bank-local coefficients in deterministic solver order.
TofBankInstrumentState: One accepted bank-local instrument.
TofChebyshevBackground: Refinable Chebyshev series on one explicit TOF interval.
TofChebyshevBasis: Sample-major analytical Chebyshev coefficient derivatives.
TofGeometryCorrelation: One unresolved lattice/instrument weighted-column pair.
TofGeometryDiagnostics: Identifiability diagnostics for the final joint geometry system.
TofInstrumentCorrelation: One unresolved weighted-Jacobian column pair.
TofInstrumentDiagnostics: Identifiability diagnostics for the final selected instrument system.
TofInstrumentParameterBound: Closed physical bounds for one selected bank-local instrument coefficient.
TofInstrumentParameterChange: One accepted physical bank-local coefficient change.
TofLatticeGeometry: TOF reflection geometry and independent lattice derivatives.
TofLatticeParameterChange: One accepted physical lattice-parameter change.
TofLeBailAnalysis: One complete runnable fixed-instrument TOF Le Bail analysis.
TofLeBailBank: One detector bank in an atomic multi-bank extraction.
TofLeBailCalculation: Display-ready TOF profile plus the fused derivative product.
TofLeBailCheckpoint: Complete immutable continuation state for fixed-instrument TOF extraction.
TofLeBailInput: Observations, fixed TOF instrument, and ordered phases.
TofLeBailIterationRecord: One accepted extraction cycle.
TofLeBailOptions: Deterministic fixed-instrument TOF extraction controls.
TofLeBailPhase: One fixed-topology phase in a TOF Le Bail extraction.
TofLeBailProjectState: Revisioned native project plus zero or one TOF analysis per TOF histogram.
TofLeBailResult: Complete fixed-instrument TOF extraction result.
TofMultiBankCheckpoint: Complete immutable continuation state for atomic multi-bank extraction.
TofMultiBankCheckpointBank: One bank’s last accepted state inside a joint checkpoint.
TofMultiBankGeometryAnalysis: One complete runnable joint multi-bank TOF geometry analysis.
TofMultiBankGeometryCheckpoint: Complete last-accepted joint geometry state.
TofMultiBankGeometryCheckpointBank: One bank’s complete accepted joint-geometry checkpoint state.
TofMultiBankGeometryInput: Shared-cell model plus selected bank-local instrument coefficients.
TofMultiBankGeometryIterationRecord: One atomically accepted extraction plus joint geometry cycle.
TofMultiBankGeometryOptions: Controls for one genuinely joint lattice/instrument step.
TofMultiBankGeometryProjectState: Revisioned project plus disjoint joint multi-bank TOF geometry analyses.
TofMultiBankGeometryResult: Complete joint shared-cell plus local-instrument result.
TofMultiBankInput: Two or more TOF banks sharing fixed phase/reflection geometry.
TofMultiBankInstrumentCheckpoint: Complete last-accepted state for exact instrument continuation.
TofMultiBankInstrumentCheckpointBank: One bank’s accepted checkpoint state.
TofMultiBankInstrumentInput: Multi-bank observations plus selected local instrument coefficients.
TofMultiBankInstrumentIterationRecord: One atomically accepted extraction plus bank-local instrument cycle.
TofMultiBankInstrumentOptions: Controls for alternating local Le Bail updates and one instrument step.
TofMultiBankInstrumentResult: Complete result from analytical bank-local TOF instrument refinement.
TofMultiBankIterationRecord: One atomically accepted multi-bank redistribution cycle.
TofMultiBankLatticeCheckpoint: Complete last-accepted state for exact shared-lattice continuation.
TofMultiBankLatticeInput: Multi-bank observations plus one or more shared phase-cell models.
TofMultiBankLatticeIterationRecord: One atomically accepted local-extraction plus shared-lattice cycle.
TofMultiBankLatticeOptions: Controls for alternating local Le Bail updates and one shared lattice step.
TofMultiBankLatticeResult: Complete result from shared analytical multi-bank TOF lattice refinement.
TofMultiBankMetrics: Aggregate residual metrics over every included sample in all banks.
TofMultiBankResult: Complete result from one atomic multi-bank fixed-cell extraction.
TofMultiBankResultBank: One bank’s accepted display state.
TofReflectionIntensity: Stable final reflection intensity.
TofSharedLatticePhase: One phase whose symmetry-independent cell is shared across every detector bank.
TofSharedLatticeState: One accepted shared-cell value.

Enums§

BackgroundError: Invalid analytical background definition, grid, or replacement.
BackgroundModel: Closed native union used by application-neutral request records.
CancellationError: Invalid cancellation token operation.
Constraint: Supported native scalar constraint records.
ConstraintError: Invalid native scalar constraint or transform input.
DiagnosticValue: Finite JSON-scalar diagnostic value.
JointRietveldError: Invalid joint native Rietveld parameter or objective state.
JointRietveldRefinementError: Invalid joint constrained-refinement state.
LatticeError: Invalid lattice parameterization, bounds, geometry, or domain generation.
LeBailError: Invalid native fixed-reflection Le Bail state or operation.
ParameterError: Invalid native parameter identity or scalar specification.
PhaseScaleEstimationError: Failure to build or solve the weighted phase-scale initialization problem.
ProfileEstimationError: Errors from effective-profile estimation.
ProfileEstimationMode: Requested complexity for effective-profile estimation.
ProfileEstimationStageKind: Stable name for one attempted estimation stage.
QuantitativeError: Invalid quantitative-phase input.
RefinementEventKind: Stable machine-readable event categories.
ResidualError: Invalid input to native residual evaluation.
RietveldError: Invalid owned native Rietveld calculation state.
RietveldGeneralObjectiveError: Invalid complete native Rietveld objective state.
RietveldGeneralParameterError: Invalid complete native Rietveld parameter state.
RietveldGeneralRefinementError: Invalid complete constrained Rietveld refinement state.
RietveldInstrumentParameter: Supported built-in monochromatic instrument and position parameters.
RietveldObjectiveError: Invalid prepared Rietveld objective state.
RietveldParameterError: Invalid native Rietveld parameter-layout state.
RietveldProjectError: Invalid project-level native Rietveld state.
RietveldRecipeError: Invalid staged Rietveld workflow state.
RietveldRecipeMode: Origin of a staged Rietveld recipe.
RietveldRefinementError: Invalid native structural refinement state.
RietveldSamplePhysicsModel: One closed built-in sample-physics model.
RuntimeError: Invalid runtime configuration, event, control order, or host callback.
SamplePhysicsError: Invalid built-in sample-physics state.
StructuralTofMultiBankError: Invalid structural multi-bank TOF request or objective product.
StructuralTofMultiBankRefinementError: Invalid bounded structural TOF refinement state.
StructuralTofProjectError: Invalid project-level structural TOF state.
TerminationReason: Stable refinement termination categories shared by every method.
TofGeometryParameterKey: Stable identity of one joint physical geometry column.
TofLeBailError: Invalid TOF Le Bail request or numerical state.
TofMultiBankError: Invalid multi-bank TOF request, shared contract, or numerical state.
TofMultiBankGeometryError: Invalid joint shared-cell/bank-local-instrument TOF state.
TofMultiBankInstrumentError: Invalid bank-local TOF instrument request or numerical state.
TofMultiBankLatticeError: Invalid shared-lattice TOF request or numerical state.
TofMultiBankProjectError: Invalid project-level joint multi-bank TOF state.
TofProjectError: Invalid project-level fixed-instrument TOF state.

Constants§

DEFAULT_MAX_LINEARIZATION_ELEMENTS: Default upper bound for reusable native structural Jacobians.

Traits§

CheckpointSink: Application-owned durable sink for one typed accepted-state checkpoint.
DifferentiableBackground: Shared immutable analytical-background contract.
RefinementEventSink: Synchronous event consumer called only at orchestration boundaries.
RuntimeClock: Monotonic second source injectable for deterministic tests.

Functions§

build_lebail_parameter_set: Build bounded typed specifications for selected fixed-geometry parameters.
build_lebail_parameter_set_with_lattice: Build bounded typed specifications including optional lattice variables.
calculate_lebail_pattern: Calculate all fixed phases through one native fused accumulation.
calculate_lebail_pattern_with_background: Calculate all fixed phases plus an optional analytical residual background.
calculate_rietveld_pattern: Calculate a complete built-in monochromatic structural pattern.
calculate_tof_lebail_pattern: Calculate one TOF pattern and all direct profile derivatives in one pass.
cw_lattice_geometry: Calculate d-spacings, CW positions, and analytical independent-variable chains.
estimate_effective_profile: Estimate an effective CW starting profile from one dominant phase.
estimate_initial_phase_scales: Estimate and install deterministic weighted non-negative phase scales.
evaluate_residuals: Evaluate masked residual arrays and standard powder residual metrics.
evaluate_tof_residuals: Evaluate residuals on an explicitly microsecond-domain TOF pattern.
extract_lebail_intensities: Perform one non-negative multiplicative redistribution step.
initialize_lebail_intensities: Return deterministic positive starting intensities in phase order.
intelligent_rietveld_recipe: Propose transparent cumulative stages from caller-authorized families.
iterate_lebail_once: Advance exactly one accepted Le Bail iteration for custom orchestration.
lebail_background_parameter_key: Return the stable key for one refinable residual-background coefficient.
lebail_instrument_parameter_key: Return the stable key for one supported CW profile coefficient.
lebail_lattice_parameter_key: Return the stable key for one symmetry-independent lattice variable.
lebail_phase_scale_key: Return the stable key for a phase scale.
lebail_reflection_position_key: Return the stable key for one independent reflection position.
quantitative_phase_analysis: Calculate Hill–Howard crystalline weight fractions in input order.
quantitative_phase_analysis_with_covariance: Calculate weight fractions and analytically propagate a phase-scale covariance.
refine_general_rietveld: Refine the complete native layout with a process-local runtime.
refine_general_rietveld_with_runtime: Refine the complete native layout through a caller-owned runtime.
refine_joint_rietveld: Refine a joint objective through a process-local runtime.
refine_joint_rietveld_with_runtime: Refine a joint objective through a caller-owned runtime.
refine_lebail: Run fixed-reflection Le Bail extraction with a workflow-owned runtime.
refine_lebail_with_runtime: Run fixed-reflection extraction with host-owned cancellation/events/checkpoints.
refine_rietveld: Refine with a process-local runtime and optional cancellation token.
refine_rietveld_with_runtime: Refine through a caller-owned runtime for events and durable checkpoints.
refine_structural_tof_multibank: Refine a guarded structural TOF objective through a process-local runtime.
refine_structural_tof_multibank_with_runtime: Refine with caller-owned cancellation, event, and checkpoint sinks.
refine_tof_lebail: Run deterministic nonnegative TOF Le Bail redistribution.
refine_tof_lebail_with_runtime: Run TOF Le Bail extraction with host-owned cancellation, events, and checkpoints.
refine_tof_multibank: Run atomic fixed-cell TOF Le Bail extraction over two or more banks.
refine_tof_multibank_geometry: Refine shared cells and selected bank-local instruments in one system.
refine_tof_multibank_geometry_with_runtime: Refine joint geometry with host cancellation/events and continuation.
refine_tof_multibank_instrument: Refine selected bank-local instrument coefficients against all TOF banks.
refine_tof_multibank_instrument_with_runtime: Refine selected bank-local instruments with cancellation and continuation.
refine_tof_multibank_lattice: Refine shared phase cells against the summed objective over all TOF banks.
refine_tof_multibank_lattice_with_runtime: Refine shared cells with host cancellation/events and optional continuation.
refine_tof_multibank_with_runtime: Run atomic multi-bank extraction with host runtime and optional continuation.
run_rietveld_recipe: Execute explicit stages while promoting only accepted physical states.
run_rietveld_recipe_with_sinks: Execute a recipe with optional shared event and checkpoint consumers.
starting_profile_from_fwhm: Construct a valid all-Gaussian starting profile from an approximate FWHM.
tof_lattice_geometry: Calculate d-spacings, TOF positions, and analytical independent-variable chains.
validate_rietveld_recipe: Validate a complete staged recipe without calculating or refining a pattern.