Crate phasesmith_io

Expand description

Bounded native input adapters for application hosts.

This crate parses external text into validated phasesmith-model and crystallographic records. It owns syntax, provenance, diagnostics, format detection, and pre-allocation limits; it does not own refinement or GUI state. Applications normally use it through phasesmith::io.

§Powder data

use phasesmith_io::{PowderFormat, PowderReadLimits, parse_powder_text};

let data = parse_powder_text(
    "20.0 100.0 2.0\n20.1 120.0 2.5\n",
    PowderFormat::Columns,
    1,
    PowderReadLimits::default(),
)?;
assert_eq!(data.pattern.sample_count(), 2);

read_powder_file and parse_powder_text support plain columns and selected GSAS formats.

§CIF structures

read_cif_file and parse_cif_text implement a bounded native CIF 1.1 path. Import produces a parser-independent CifStructure containing a validated cell, exact symmetry operations, independent atom sites, uncertainties, metadata, diagnostics, and source provenance.

use phasesmith_io::{CifReadLimits, parse_cif_text};

let cif = r#"
data_demo
_cell_length_a 5.431(1)
_cell_length_b 5.431(1)
_cell_length_c 5.431(1)
_cell_angle_alpha 90
_cell_angle_beta 90
_cell_angle_gamma 90
_space_group_IT_number 227
loop_
_atom_site_label
_atom_site_type_symbol
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
Si1 Si 0 0 0
"#;
let result = parse_cif_text(cif, None, true, CifReadLimits::default())?;
assert_eq!(result.selected_block, "demo");
assert_eq!(result.structure.sites[0].element_symbol, "Si");
assert_eq!(result.structure.cell_standard_uncertainties[0], Some(0.001));

The block argument is the name after data_. Strict mode requires an explicit selection for a multi-block document and rejects conflicting scientific definitions. Permissive mode may make a documented recovery, such as selecting the first block or renaming a duplicate site ID, but every such decision is returned as a stable CifDiagnostic. Applications should display and persist these diagnostics rather than treating a successful parse as warning-free.

Symmetry precedence is explicit operations, Hall symbol, Hermann–Mauguin symbol, then International Tables number. If no definition exists, P1 is returned with a warning. Atom sites require complete fractional or Cartesian coordinates. Occupancy defaults to one; CIF B displacement values are converted to U by U = B/(8*pi^2). Magnetic, modulated/superspace, and macromolecular feature families are not interpreted.

The facade’s CIF input guide documents supported content, strict/permissive behavior, stable result fields, and the subsequent conversion into refinement state.

§Space groups

Space-group lookup functions expose database provenance and do not require a CIF parser. Use space_group_by_number or space_group_by_symbol for a conventional setting, and space_group_from_hall_symbol when a general Hall expression is already available.

Keep default limits for ordinary trusted files; tighten them when accepting untrusted uploads. Limit errors are distinct from syntax and domain errors.

Structs§

CifAnisotropicDisplacement: Fixed anisotropic displacement attached to one site.
CifAtomSite: One independent atom site imported from CIF.
CifDiagnostic: One stable CIF import diagnostic.
CifReadLimits: Resource limits checked before and during CIF parsing.
CifReadResult: One selected CIF structure plus block-selection context.
CifStructure: Parser-independent native crystallographic structure.
CifStructureSource: Source provenance retained after CIF parsing.
GsasTofInstrumentData: One translated legacy GSAS TOF bank plus source metadata.
GsasTofInstrumentReadLimits: Resource limit checked before decoding a legacy instrument file.
PowderData: One observed powder dataset plus source metadata.
PowderReadLimits: Resource limits checked before or during parsing.
SpaceGroupDatabaseProvenance: Reviewed source and version for native space-group lookup data.
SpaceGroupInfo: Human identifiers plus an exact engine-owned conventional operation set.
TofPowderData: One observed TOF powder dataset with an explicitly microsecond-domain axis.

Enums§

CifDiagnosticSeverity: Stable diagnostic severity for a successfully returned import.
CifIoError: Native CIF syntax, limit, lookup, or domain failure.
DisplacementConvention: Original CIF displacement convention.
GsasTofInstrumentIoError: Stable failure categories for legacy GSAS TOF instrument import.
PowderFormat: Caller-selected or detected powder text format.
PowderIoError: Native powder input failure with stable categories.
SpaceGroupLookupError: Native space-group lookup or database-conversion failure.
TofPowderFormat: Caller-selected or detected microsecond-domain powder text format.

Constants§

NATIVE_CIF_BACKEND: Native CIF parser implementation identifier.
NATIVE_CIF_BACKEND_VERSION: Version of the native CIF adapter contract.
SPACE_GROUP_DATABASE_PROVENANCE: Provenance for the pure-Rust conventional space-group database.

Functions§

parse_cif_text: Parse bounded UTF-8 CIF text into one selected native structure.
parse_gsas_tof_instrument_text: Parse one bounded legacy GSAS TOF profile-function-1 or -3 bank from text.
parse_powder_text: Parse bounded UTF-8 powder text without filesystem access.
parse_tof_powder_text: Parse one bounded reduced TOF input into bin-center intensity densities.
parse_tof_powder_text_as: Parse bounded microsecond-domain powder text with an explicit convention.
read_cif_file: Read and parse one bounded UTF-8 CIF file.
read_gsas_tof_instrument_file: Read one bounded legacy GSAS TOF profile-function-1 or -3 bank.
read_powder_file: Read and parse one bounded UTF-8 powder file.
read_tof_powder_file: Read one bounded reduced TOF file into bin-center intensity densities.
read_tof_powder_file_as: Read one bounded microsecond-domain powder file with an explicit convention.
space_group_by_hall_symbol: Resolve an exact Hall symbol, preserving its setting and origin choice.
space_group_by_number: Resolve an International Tables number in the conventional standard setting.
space_group_by_symbol: Resolve a Hermann–Mauguin, full-setting, or Hall symbol.
space_group_from_hall_symbol: Parse a general Hall expression into an exact engine-owned operation set.