API: techniques#

This page lists the calls that belong to one technique, each under the technique that uses it.

A fit that uses none of these techniques needs only API: everyday calls.

The batch index#

Diagnostics over a batch#

rx.diagnostics_summary( results: Iterable[RefinementResult], deliverable: str | None = None, levels: dict[str, str] | None = None, ) → DiagnosticsSummary#: The diagnostics of a batch of results as counts: each code’s firing rate, the warning rows a result carries per purpose, and the codes ranked by their share of the warnings (WP-2037).

class rx.DiagnosticsSummary#

The diagnostics of a batch of results as counts, from diagnostics_summary.

n_results: int#
deliverable: str | None = None#
levels: dict[str, str] = {}#
codes: list[CodeTally] = []#
warnings_per_result: dict[str, float] = {}#
pareto: list[ParetoRow] = []#

class rietx.report.batch.CodeTally#

One code’s firing over a batch.

code: str#
n_results: int#
rate: float#
n_rows: int#
n_error: int#
n_warning: int#
n_info: int#

class rietx.report.batch.ParetoRow#

One code’s share of a batch’s warning rows, in Pareto order.

code: str#
n_warning: int#
share: float#
cumulative: float#

The figure index#

Drawing a structure#

viz.render_structure( structure, phase: int = 0, *, mode: str = 'ball', view='opening', up=None, turn: str | None = None, size=1000, supersample: int = 2, probability: float | None = None, bond_tolerance: float | None = None, max_atoms: int | None = None, exaggeration: float = 1.0, stick: float = 1.0, hidden=(), boundary: bool = True, cell: bool = True, polyhedra=None, axis_labels: bool = True, atom_labels: bool = False, outline: bool = False, background='white', path=None, dpi: float | None = None, ) → StructureFigure#: Draw one phase of a structure as the GUI’s structure viewer draws it.

class rietx.viz.figure3d.StructureFigure#

What render_structure drew.

image: np.ndarray#
rotation: list[list[float]]#
pixels_per_angstrom: float#
origin: list[float]#
atoms: list[dict]#
letters: list[dict]#
path: str | None = None#
palette: dict[str, str] = {}#
report: FigureReport | None = None#
candidates: list[dict] = []#
recipe: dict = {}#

Figure report#

class rietx.viz.figure3d.FigureReport#

The numbers a look at the figure would give.

hidden: float#
hidden_atoms: list[int]#
stacked: float#
dangling_bonds: int#
label_overlaps: int#
label_atom_overlaps: int#
label_bond_overlaps: int#
empty: float#
cut: dict[str, int]#
note: str#
warnings: list[str] = []#

Selecting part of a structure#

viz.keep( geometry: Mapping, mask, *, complete: bool | str = False, ) → dict#: The geometry with only the atoms mask keeps, every index consistent.

viz.select( geometry: Mapping, *, species=None, element=None, label=None, site=None, boundary: bool | None = None, ) → np.ndarray#: The atoms of the named sites, as a boolean array over atoms.

viz.plane( geometry: Mapping, hkl, distance: float, *, width: float | None = None, inverse: bool = False, units: str = 'd', ) → np.ndarray#: The atoms on the origin side of the plane (hkl) at distance.

viz.sphere(geometry: Mapping, centre, radius: float) → np.ndarray#: The atoms within radius Å of centre, itself included.

viz.component( geometry: Mapping, atom: int, *, via: str = 'bonds', ) → np.ndarray#: The connected piece of the figure holding atom.

viz.periodicity(geometry: Mapping, mask) → int#: How many independent lattice directions the atoms mask keeps repeat in, 0 to 3.

viz.recolour(geometry: Mapping, mask, colour) → dict#: The geometry with the masked atoms, and the polyhedra centred on them, in colour.

Plotting a pattern#

viz.plot_pattern( data, *, path: str | None = None, two_theta_range: tuple[float, float] | None = None, x_axis: str = 'two_theta', wavelength: float | None = None, y_scale: str = 'linear', style: str = 'light', figsize: tuple[float, float] | None = None, font_size: float = 11.0, dpi: int = 300, title: str | None = None, model=None, )#: A measured pattern on its own, before any model exists.

The other programs’ files index#

Recipes and instrument files#

rx.read_recipe( source: str | Path | dict, *, diagnostics: list[Diagnostic] | None = None, ) → Recipe#: Read a PowderLine GSASII_Rietveld recipe.

rx.write_recipe_tables( refinement, out_dir: str | Path, *, phase_names: dict[str, str] | None = None, ) → dict[str, Path]#: Write a finished refinement as PowderLine’s four output tables.

rx.read_gsas_prm( path: str | Path, *, profile_set: int | None = None, diagnostics: list[Diagnostic] | None = None, ) → Instrument#: Read a GSAS-I .prm instrument-parameter file as a frozen Instrument.

rx.write_gsas_prm( instrument: Instrument, path: str | Path, *, header: str = '', diagnostics: list[Diagnostic] | None = None, )#: Write instrument to path as a GSAS-I .prm.

rx.read_gsas_tof_iparm( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → dict[int, Instrument]#: Read a GSAS-I TOF instrument-parameter file: {bank number: Instrument}.

rx.read_gsas2_instprm( path: str | Path, *, bank: int | None = None, diagnostics: list[Diagnostic] | None = None, ) → Instrument#: Read a GSAS-II .instprm file as a frozen Instrument.

rx.write_gsas2_instprm( instrument: Instrument, path: str | Path, *, diagnostics: list[Diagnostic] | None = None, )#: Write instrument to path as a GSAS-II .instprm.

Other programs’ projects#

rx.read_project_model( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → ProjectModel#: Read a refinement another program wrote, dispatching on content.

rx.identify_project_format(path: str | Path) → ProjectFormat#: Name the registered project format that claims path.

rx.read_topas_inp( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → TopasModel#: Parse a .inp.

rx.write_topas_inp( structure: Structure, path: str | Path, *, diagnostics: list[Diagnostic] | None = None, p1_expand: bool | 'auto' = False, free=None, scale=None, instrument=None, pattern=None, )#: Write.

rx.read_fullprof_pcr(path: str | Path) → FullProfModel#: Parse a .pcr.

rx.write_fullprof_pcr( structure: Structure, path: str | Path, *, instrument: Instrument | None = None, diagnostics: list[Diagnostic] | None = None, write_zero_shift: bool = False, )#: Write a .pcr.

rx.read_gsas_exp( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → GsasModel#: Read a GSAS-I .EXP experiment file.

rx.write_gsas_exp( structure: Structure, path: str | Path, *, title: str = '', diagnostics: list[Diagnostic] | None = None, )#: Write structure to path as a GSAS-I .EXP.

rx.read_gsas2_gpx( path: str | Path, *, diagnostics: list[Diagnostic] | None = None, ) → Gsas2Model#: Read a GSAS-II .gpx project file.

rx.write_gsas2_phase_cif( structure, path: str | Path, *, diagnostics: list[Diagnostic] | None = None, )#: Write the phase CIF GSAS-II imports.

The magnetic structure index#

Determining a magnetic structure#

rx.solve_magnetic( refinement, data, *, phase: int = 0, sites: Sequence[str] | None = None, species: Sequence[str] | None = None, ion: str | dict[str, str] | None = None, g: float | dict[str, float] | None = None, k=None, top_k: int = 3, d_min: float = 1.5, magnitude: float = 2.0, plan: RefinementPlan | None = None, nuclear_group: str = 'parent', generator=None, tie_width: float = 6.0, k_trials: int = 2, k_tie_width: float = 10.0, cif_dir=None, tie_to_parent: bool = False, ) → MagneticSolution#: Determine a magnetic structure from a converged nuclear fit, or abstain.

class rx.MagneticSolution#

The ranked list, the criterion, and the verdict or the abstention.

verdict: str#
reason: str#
criterion: str#
phase: str#
space_group: str#
k: tuple[str, str, str] | None#
k_route: str#
k_reason: str#
k_candidates: tuple[tuple[str, int, int], ...]#
sites: tuple[str, ...]#
n_residual_peaks: int#
n_on_nuclear_lines: int#
n_on_forbidden_lattice_points: int#
n_unexplained: int#
trials: tuple[MagneticTrial, ...]#
tied: tuple[int, ...]#
tie_width: float#
d_min: float#
nuclear_rwp: float | None#
nuclear_gof: float | None#
nuclear_r_magnetic: float | None#
n_magnetic_channels: int#
caveats: tuple[str, ...] = ()#
k_trials: tuple[KTrialSummary, ...] = ()#
diagnostics: tuple[Diagnostic, ...] = ()#
subgroup_audit: tuple[SubgroupAudit, ...] = ()#
subgroup_note: str = ''#

class rx.MagneticTrial#

One powder-equivalence class, refined once, with what the data said.

class_index: int#
representative: str#
members: tuple[str, ...]#
site: str#
irrep: str#
direction: str#
bns_number: str#
uni_number: int | None#
msg_type: int | None#
free_amplitudes: int#
determinable_amplitudes: int | None#
status: str#
refusal: str | None = None#
rwp: float | None = None#
gof: float | None = None#
delta_bic: float | None = None#
r_magnetic: float | None = None#
n_moment_parameters: int | None = None#
n_free_parameters: int | None = None#
moments: tuple[MomentRow, ...] = ()#
held: tuple[str, ...] = ()#
anti_translation_drift: float | None = None#
n_starts: int | None = None#
n_minima: int | None = None#
start: str | None = None#
fit_status: str | None = None#
reference_status: str | None = None#

class rx.MomentRow#

One site’s refined moment inside one trial.

label: str#
ion: str#
magnitude: float#
esd: float | None#
crystalaxis: tuple[float, float, float]#
supported: bool#
unmeasured_directions: tuple[str, ...] = ()#
paired_with: tuple[str, ...] = ()#
paired_magnitude: float | None = None#
paired_magnitude_esd: float | None = None#

Displacive mode amplitudes#

rietx.crystallography.representation.distortion.mode_amplitudes( parent, child, transform, *, reference: str = 'average', tolerance: float = 1.5, ) → ModeDecomposition#: Decompose a child structure into A_τ per (k, irrep, direction), in Å.

class rietx.crystallography.representation.distortion.ModeDecomposition#

A child decomposed against its parent into A_τ per (k, irrep, direction).

rows: tuple[ModeAmplitude, ...]#
total: float#
residual: float#
translation: tuple[float, float, float]#
displacements: np.ndarray#
basis: ModeBasis#

class rietx.crystallography.representation.distortion.ModeAmplitude#

One irrep’s share of a child’s distortion, in Å.

k: tuple[str, str, str]#
irrep: str#
isotropy_group: str#
primary: bool | None#
n_modes: int#
amplitude: float#
mode_amplitudes: tuple[float, ...]#

rietx.crystallography.representation.distortion.distortion_basis( parent, child, transform, *, reference: str = 'average', ) → ModeBasis#: Every symmetry-adapted mode a child of parent admits, in Å.

Displacive candidates of a parent#

rietx.crystallography.magnetic.isotropy.distortion_candidates( parent, k, sites=None, ) → tuple[DistortionCandidate, ...]#: Every displacive candidate of parent at k, with its child and modes in Å.

class rietx.crystallography.magnetic.isotropy.DistortionCandidate#

One displacive candidate of a parent: its child, (P, p) and its modes in Å.

candidate: MagneticCandidate#
child: object#
transform: tuple[np.ndarray, np.ndarray]#
basis: object#
sites: tuple[str, ...]#