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 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.