# 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](api.html.md). ## The batch index ### Diagnostics over a batch ### rx.diagnostics_summary(results: Iterable[[RefinementResult](api.html.md#rx.RefinementResult)], deliverable: str | None = None, levels: dict[str, str] | None = None) → [DiagnosticsSummary](#rx.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](#rietx.viz.figure3d.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](api.html.md#rx.Diagnostic)] | None = None) → [Recipe](api-types.html.md#rx.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](api.html.md#rx.Diagnostic)] | None = None) → [Instrument](api.html.md#rx.Instrument) Read a GSAS-I `.prm` instrument-parameter file as a **frozen** `Instrument`. ### rx.write_gsas_prm(instrument: [Instrument](api.html.md#rx.Instrument), path: str | Path, \*, header: str = '', diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) Write `instrument` to `path` as a GSAS-I `.prm`. ### rx.read_gsas_tof_iparm(path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) → dict[int, [Instrument](api.html.md#rx.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](api.html.md#rx.Diagnostic)] | None = None) → [Instrument](api.html.md#rx.Instrument) Read a GSAS-II `.instprm` file as a **frozen** `Instrument`. ### rx.write_gsas2_instprm(instrument: [Instrument](api.html.md#rx.Instrument), path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.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](api.html.md#rx.Diagnostic)] | None = None) → [ProjectModel](api-types.html.md#rx.ProjectModel) Read a refinement another program wrote, dispatching on *content*. ### rx.identify_project_format(path: str | Path) → [ProjectFormat](api-types.html.md#rx.ProjectFormat) Name the registered project format that claims `path`. ### rx.read_topas_inp(path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) → TopasModel Parse a `.inp`. ### rx.write_topas_inp(structure: [Structure](api.html.md#rx.Structure), path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.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](api.html.md#rx.Structure), path: str | Path, \*, instrument: [Instrument](api.html.md#rx.Instrument) | None = None, diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None, write_zero_shift: bool = False) Write a `.pcr`. ### rx.read_gsas_exp(path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) → GsasModel Read a GSAS-I `.EXP` experiment file. ### rx.write_gsas_exp(structure: [Structure](api.html.md#rx.Structure), path: str | Path, \*, title: str = '', diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) Write `structure` to `path` as a GSAS-I `.EXP`. ### rx.read_gsas2_gpx(path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.Diagnostic)] | None = None) → Gsas2Model Read a GSAS-II `.gpx` project file. ### rx.write_gsas2_phase_cif(structure, path: str | Path, \*, diagnostics: list[[Diagnostic](api.html.md#rx.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](api.html.md#rx.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](#rx.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](#rietx.crystallography.representation.distortion.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](#rietx.crystallography.magnetic.isotropy.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, ...]`