xharpy package

Subpackages

Submodules

xharpy.cli module

xharpy.conversion module

This module contains conversions, that are needed in different parts of the library. It is not meant to import from anywhere within XHARPy so that its functions can be import without circular imports

xharpy.conversion.calc_sin_theta_ov_lambda(cell_mat_f: jax.numpy.ndarray, index_vec_h: jax.numpy.ndarray) → jax.numpy.ndarray

Calculate the resolution in sin(theta)/lambda for the given set of Miller indicees

Parameters:

  • cell_mat_f (jnp.ndarray) – size (3, 3) array containing the reciprocal lattice vectors

  • index_vec_h (jnp.ndarray) – size (H, 3) array of Miller indicees of reflections

Returns:

sin_theta_ov_lambda – size (H) array containing the calculated resolution values

Return type:

jnp.ndarray

xharpy.conversion.cell_constants_to_M(a: float, b: float, c: float, alpha: float, beta: float, gamma: float, crystal_system: str = 'triclinic')

Generates a matrix with the three lattice vectors as row vectors

Parameters:

  • a (float) – cell constant a in Angstroem

  • b (float) – cell constant b in Angstroem

  • c (float) – cell constant c in Angstroem

  • alpha (float) – cell angle alpha in degree

  • beta (float) – cell angle beta in degree

  • gamma (float) – cell angle gamma in degree

  • crystal_system (str, optional) – Crystal system of the evaluated structure. Possible values are: ‘triclinic’, ‘monoclinic’ ‘orthorhombic’, ‘tetragonal’, ‘hexagonal’, ‘trigonal’ and ‘cubic’. Does not make a difference for the calculation of the matrix, but does make a difference for the derivatives to the cell parameters

Returns:

cell_mat_m – size (3, 3) array containing the cell vectors as row vectors

Return type:

jnp.ndarray

xharpy.conversion.expand_symm_unique(type_symbols: List[str], coordinates: ndarray, cell_mat_m: ndarray, symm_mats_vec: Tuple[ndarray, ndarray], skip_symm: Dict[str, List[int]] = {}, magmoms: ndarray | None = None) → Tuple[ndarray, List[str], ndarray, ndarray | None]

Expand the type_symbols and coordinates for one complete unit cell. Atoms on special positions appear only once. For disorder on a special position use skip_symm.

Parameters:

  • type_symbols (List[str]) – Element symbols of the atoms in the asymmetric unit

  • coordinates (npt.NDArray[np.float64]) – size (N, 3) array of fractional atomic coordinates

  • cell_mat_m (npt.NDArray[np.float64]) – Matrix with cell vectors as column vectors, (Angstroem)

  • symm_mats_vec (Tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]) – size (K, 3, 3) array of symmetry matrices and size (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • skip_symm (Dict[str, List[int]], optional) – Symmetry elements with indexes given the list(s) in the dictionary values with not be applied to the respective atoms with the atom names given in the key(s). Indexes need to be identical to the ones in symm_mats_vec., by default {}

  • magmoms (Optional[npt.NDArray[np.float64]], optional) – Magnetic Moments. The enforced symmetry might not be correcz, by default None

Returns:

  • symm_positions (npt.NDArray[np.float64]) – size (M, 3) array of all unique atom positions within the unit cell

  • symm_symbols (List[str]) – ist of length M with element symbols for the unique atom positions within the unit cell

  • reverse_indexes (npt.NDArray[np.float64]) – size (K, N) array with indexes mapping the unique atom positions back to the individual symmetry elements and atom positions in the asymmetric unit

  • symm_magmoms (Optional[npt.NDArray[np.float64]]]) – magnetic moments for symmetry generated atoms. Undertested!

xharpy.conversion.ucif2ucart(cell_mat_m: jax.numpy.ndarray, u_mats: jax.numpy.ndarray) → jax.numpy.ndarray

Calculate anisotropic displacement matrices in the cartesian convention from the displacement matrices in the cif convention see: R. W. Grosse-Kunstleve and P. D. Adams J. Appl. Cryst 2002, p.478 eq. 3a + 4a

Parameters:

  • cell_mat_m (jnp.ndarray) – size (3,3) array containing the cell vectors as row vectors

  • u_mats (jnp.ndarray) – size (N, 3, 3) array containing the anisotropic displacement matrices in cif format

Returns:

u_cart – size (N, 3, 3) array of the matrices in cartesian convention

Return type:

jnp.ndarray

xharpy.io module

This module containts the input/output routines for the XHARPy library

xharpy.io.add_density_entries_from_fcf(cif_path: str, fcf6_path: str)

Adds the density entries to a cif file starting from the fcf6 file. This is necessary because so far the difference density calculation is not working properly. This introduces a dependency on the rather large cctbx/iotbx library

Parameters:

  • cif_path (str) – path to the cif-file to be completed

  • fcf6_path (str) – path to the fcf6 file to be used for the difference electron density calculation

xharpy.io.add_from_cif(name: str, cif: OrderedDict, esd: bool = False, string_sign: bool = True) → str

Try to add a value from another cif file, read in by ciflike_to_dict

Parameters:

  • name (str) – Name of the cif entry

  • cif (OrderedDict) – The dictionary generated from the read in cif file

  • esd (bool, optional) – Value comes with an estimated standard deviation so this is considered as well, by default False

  • string_sign (bool, optional) – Value is a string and should also be written ‘like this’, by default True

Returns:

Formatted entry if the value is present in the cif file. Otherwise the entry will be marked with the . for a missing entry.

Return type:

str

xharpy.io.cif2atom_type_table_string(cif: OrderedDict, version: str, ishar: bool = True) → str

Helper function to create the atom_type table from a given cif

Parameters:

  • cif (OrderedDict) – The dictionary generated from the read in cif file

  • versionmajor (str) – current XHARPy version

  • ishar (bool, optional) – refinement is a Hirshfeld Atom Refinement in XHARPy, by default True

Returns:

Formatted atom_type table

Return type:

str

xharpy.io.cif2data(cif_path: str, cif_dataset: str | int = 0) → Tuple[DataFrame, ndarray, ndarray, Tuple[jax.numpy.ndarray, jax.numpy.ndarray], List[str], float]

Function to generate the needed variables used for the futher refinement from a given cif file.

Parameters:

  • cif_path (str) – Path to the cif file, that should be used as source for the structure information

  • cif_dataset (Union[str, int], optional) – dataset within that cif file, that is supposed to be used, when a string is passed as the argument, the dataset is selected by name. When an integer is passed it is selected by index. If you have named with numbering, pass the number as a string (e.g. ‘2’), by default 0

Returns:

  • atom_table (pd.DataFrame) – pandas DataFrame that contains the atomic information. Columns are named like their counterparts in the cif file but without the common start for each table (e.g. atom_site_fract_x -> fract_x). All tables are merged on the atom label. f’ and f’’ are merged on atom_type

  • cell (np.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (np.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • symm_instructions (List[str]) – List of symmetry instructions from the cif-file. Needed for writing a new cif file

  • wavelength (float) – Measurement wavelength in Angstroem

xharpy.io.cif2space_group_table_string(cif: OrderedDict) → str

Helper function the generate the space_group table from a given cif file

Parameters:

cif (OrderedDict) – The dictionary generated from the read in cif file

Returns:

Formatted space_group table

Return type:

string

xharpy.io.cif2tsc(tsc_path: str, cif_path: str, cif_dataset: str | int, export_dict: Dict[str, Any], computation_dict: Dict[str, Any], tsc_core_path: str | None = None) → None

Can be used to create a tsc file directly from a given cif file and the necessary options.

Parameters:

  • tsc_path (str) – Path where the new tsc file is meant to be written

  • cif_path (str) – Path to the input cif file

  • cif_dataset (Union[str, int]) – indentifier of dataset in cif file. If this parameter is a string, the function will search for data_*cif_dataset* and use the values. An integer will be interpreted as an index, starting with 0 as usual in python.

  • export_dict (Dict[str, Any]) –

    Dictionary with options for the .tsc export

    • f0j_source (str) : Can be one of the implemented sources for atomic form factors. The most common options are ‘gpaw’, ‘gpaw_mpi’ and ‘qe’

    • core (str): can be either ‘constant’, which means the core densitsy will be evaluated on a separate spherical grid and assigned to the source atom completely, or ‘combine’ in which case the core density is expanded and partitioned in the same way the valence density is

    • core_io (Tuple[str, str]): Expects a tuple where the first entry can be ‘save’, ‘load’, ‘none’ which is the action that is taken with the core density. The second argument in the tuple is the filename, to which the core density is saved to or loaded from

    • resolution_limit (Union[float, str]) : resolution limit up to which the atomic form factors are evaluated. Can either be a float which is the value in Angstrom or the string ‘cif’ in which case the value will be inferred from the cif entries, by default 0.40

  • computation_dict (Dict[str, Any]) – Dict with options that are passed on to the f0j_source. See the individual calc_f0j functions for a more detailed description

Raises:

  • NotImplementedError – f0j_source not implemented

  • ValueError – Tried to load core density, but core density does not have the same number of entries as the hkl indicees

  • NotImplementedError – Type of core description not implemented

xharpy.io.cif_entry_string(name: str, value: None | str | float | int, string_sign: bool = True) → str

Create a cif line from the given values

Parameters:

  • name (str) – Name of the cif entry without preceding underscore

  • value (Union[None, str, float, int]) – Value corresponding to the cif entry in one of the given types.

  • string_sign (bool, optional) – Embed an entry of type cif ‘like this’, Lots of options in cif file are formatted without the string sign if there is a limited number of options. Can also be used to write out numerical values with esd, by default True

Returns:

Output line for the cif entry

Return type:

str

Raises:

NotImplementedError – Unknown variable type for value. Either implement or cast into one of the known ones (str with string_sign False should always work)

xharpy.io.ciflike_to_dict(filename: str, return_descr: str | int | None = None, resolve_esd: bool = True) → Dict[str, Dict] | Dict

Function to read in cif or cif-like (e.g. fcf) files. Can return all structures contained in the file. To return only the data of one structure use return_descr to select by dataset name or index.

Parameters:

  • filename (str) – Path to a cif or cif-like file

  • return_descr (Union[str, int, None], optional) – Can be used to only return a specific dataset from the cif file if a string is given as argument, the dataset with that name is returned. An integer will return the dataset by index (i.e. 0 will give the first dataset in the file), None will return a dict with all datasets, with the dataset name as key, by default None

  • resolve_esd (bool, optional) – If this argument is set to true, will split arguments, which have an esd into two arguments: arg, arg_esd, False will return a string in this case (i.e. ‘12(3)’), by default True

Returns:

cif_content – Returns a dictionary of dataset_name, dataset_dict pairs or a single dataset as OrderedDict. Within the dataset all entries are given as key, value pairs with the key being the entry in the cif_file without the preceding underscore. The routine will try to cast the value into a float, int or string, depending on whether digits, digits and a dot or other characters are present. All loops are given as a list of pandas DataFrame objects under the ‘loops’ keyword.

Return type:

Union[Dict[str, Dict], Dict]

Raises:

  • e – If an exception occurs it is raised after printing the line in the cif file for debugging purposes

  • ValueError – The return_descr was in an invalid type

xharpy.io.create_angle_table(angles: List[Tuple[str, str, str, str, str]], construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray, cell: jax.numpy.ndarray, cell_esd: jax.numpy.ndarray, crystal_system: str, symm_mats_vecs: Tuple[ndarray, ndarray]) → str

Create a angle table for the given parameters

Parameters:

  • bonds (List[Tuple[str, str, str, str, str]]) – List with tuples of atom names. Angles spanned the atoms are output to the angle table and two cif symmetry codes for the first and third atom of the angle

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • parameters (jnp.ndarray) – final refined parameters

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (jnp.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • crystal_system (str) – Crystal system of the evaluated structure. Possible values are: ‘triclinic’, ‘monoclinic’ ‘orthorhombic’, ‘tetragonal’, ‘hexagonal’, ‘trigonal’ and ‘cubic’. Is considered for the esd calculation.

Returns:

Formatted geom_angle table

Return type:

str

xharpy.io.create_aniso_table_string(parameters: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], cell: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray) → str

Create a formatted atom_site_aniso table from the given arguments

Parameters:

  • parameters (jnp.ndarray) – final refined parameters

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

Returns:

Formatted atom_site_aniso string

Return type:

str

xharpy.io.create_atom_site_table_string(parameters: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], cell: jax.numpy.ndarray, cell_esd: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray, crystal_system: str) → str

Helper function to create the atom_site table from the refined parameters

Parameters:

  • parameters (jnp.ndarray) – final refined parameters

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (jnp.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

  • crystal_system (str) – Crystal system of the evaluated structure. Possible values are: ‘triclinic’, ‘monoclinic’ ‘orthorhombic’, ‘tetragonal’, ‘hexagonal’, ‘trigonal’ and ‘cubic’. Is considered for the esd calculation.

Returns:

Formatted atom_site table

Return type:

str

Raises:

NotImplementedError – Non-implemented adp_type

xharpy.io.create_diff_density_entries(symm_mats_vecs, index_vec_h, scaled_intensity, structure_factors, cell_mat_m, dims=array([53, 53, 53]))

This function currently only adds empty entries that need to be filled in with cctbx as the current implementation produces significantly different results

xharpy.io.create_distance_table(bonds: List[Tuple[str, str, str]], construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray, cell: jax.numpy.ndarray, cell_esd: jax.numpy.ndarray, crystal_system: str, symm_mats_vecs: Tuple[ndarray, ndarray]) → str

Create a distance table for the given parameters

Parameters:

  • bonds (List[Tuple[str, str, str]]) – List with tuples of atom names and a corresponding cif symmetry code for the second atom. Distances between the atoms in the tuple are output to the bond table.

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • parameters (jnp.ndarray) – final refined parameters

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (jnp.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • crystal_system (str) – Crystal system of the evaluated structure. Possible values are: ‘triclinic’, ‘monoclinic’ ‘orthorhombic’, ‘tetragonal’, ‘hexagonal’, ‘trigonal’ and ‘cubic’. Is considered for the esd calculation.

Returns:

Formatted geom_bond table

Return type:

str

xharpy.io.create_extinction_entries(parameters: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray, refinement_dict: Dict[str, Any]) → str

Create the set of extinction related entries as string output

Parameters:

  • parameters (jnp.ndarray) – final refined parameters

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

  • refinement_dict (Dict[str, Any]) – Dictionary with refinement options. For detailed options see refinement function in core

Returns:

Formatted string for output

Return type:

str

Raises:

NotImplementedError – Used extinction method is not implemented in this output function

xharpy.io.create_fcf4_table(index_vec_h: jax.numpy.ndarray, structure_factors: jax.numpy.ndarray, intensity: jax.numpy.ndarray, esd_int: jax.numpy.ndarray, scaling: float) → str

Create a formatted fcf4 table for output in cif file

Parameters:

  • index_vec_h (jnp.ndarray) – size (H, 3) array of Miller indicees of observed reflections

  • structure_factors (jnp.ndarray) – size (H)-sized array with complex structure factors for each reflection

  • intensity (jnp.ndarray) – size (H) array of observed reflection intensities

  • esd_int (jnp.ndarray) – Estimated standard deviation of the observed reflection intensites

  • scaling (float) – overall scaling factor

Returns:

formatted fcf4 table

Return type:

str

xharpy.io.create_gc3_table_string(parameters: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], cell: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray) → str

Create a formatted atom_site_anharm_GC_C table if any values are different from zero

Parameters:

  • parameters (jnp.ndarray) – final refined parameters

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

Returns:

Formatted atom_site_anharm_GC_C table if any value different from zero, otherwise an empty string is returned

Return type:

str

xharpy.io.create_gc4_table_string(parameters: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], cell: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray) → str

Create a formatted atom_site_anharm_GC_D table if any values are different from zero

Parameters:

  • parameters (jnp.ndarray) – final refined parameters

  • construction_instructions (List[AtomInstructions]) – list of AtomInstructions used in the refinement.

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • var_cov_mat (jnp.ndarray) – variance covariance matrix of the final refinement step

Returns:

Formatted atom_site_anharm_GC_D table if any value different from zero, otherwise an empty string is returned

Return type:

str

xharpy.io.entries2atom_string(label: str, sfac_index: int, xyz: ndarray, uij: ndarray, occupancy: float) → str

Helper function to create a shelxl .res atom string from the given parameters

Parameters:

  • label (str) – Atom label

  • sfac_index (int) – SFAC index within shelxl

  • xyz (np.ndarray) – fractional coordinates

  • uij (np.ndarray) – Anisotropic displacement parameters

  • occupancy (float) – occupancies

Returns:

The correct atomic string for the SHELXL output

Return type:

str

xharpy.io.f0j2tsc(file_name: str, f0j: ndarray, construction_instructions: List[AtomInstructions], symm_mats_vecs: Tuple[ndarray, ndarray], index_vec_h: ndarray, remove_anom: bool = True)

Write a tsc file from the atomic form factor array For the format see: https://arxiv.org/pdf/1911.08847.pdf.

Parameters:

  • file_name (str) – Path to file, where the .tsc should be written

  • f0j (np.ndarray) – size (K, N, H) array of atomic form factors for all reflections and symmetry generated atoms within the unit cells. Atoms on special positions are present multiple times and have the atomic form factor of the full atom. Can be obtained from a calc_f0j function or the informationdispersion_real = jnp.array([atom.dispersion_real for atom in construction_instructions]) dispersion_imag = jnp.array([atom.dispersion_imag for atom in construction_instructions]) f_dash = dispersion_real + 1j * dispersion_imag dict of a refinement

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • symm_mats_vecs (Tuple[np.ndarray, np.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • index_vec_h (np.ndarray) – size (H) vector containing Miller indicees of the measured reflections

  • remove_anom (bool, optional) – Determines, whether the dispersion correction should be subtracted. Should be True if you obtained the f0j values from a refinement, Should be False if you obtained them from a calc_f0j function, by default True

xharpy.io.fcf2hkl_pd(fcf_path: str, fcf_dataset: str | int = 0) → DataFrame

Helper function to generate a DataFrame from a given .fcf file. Might also work with cif files if a fcf-like loop is present

Parameters:

  • fcf_path (str) – Path to the fcf file

  • fcf_dataset (Union[str, int], optional) – dataset within that fcf file, that is supposed to be used, when a string is passed as the argument, the dataset is selected by name. When an integer is passed it is selected by index. If you have named with numbering, pass the number as a string (e.g. ‘2’), by default 0

Returns:

hkl – Dataframe with named columns: ‘h’, ‘k’, ‘l’, ‘intensity’, ‘esd_int’

Return type:

pd.DataFrame

Raises:

ValueError – The file contains no table with refln_F_squared_meas as a column

xharpy.io.generate_core_refinement_string(refinement_dict, parameters, var_cov_mat)
xharpy.io.instructions_to_constraints(names: List[str], instructions: str) → ConstrainedValues

Helper function to generate symmetry constraints for a special position from a single atom entry in the the shelxl .lst file

Parameters:

  • names (List[str]) – names of variables to search for at the call

  • instructions (str) – instructions to search in

Returns:

A valid ConstrainedValues instance for the set of variables

Return type:

ConstrainedValues

xharpy.io.lst2constraint_dict(filename: str) → Dict[str, Dict[str, ConstrainedValues]]

Helper function to create a constraint dict for the refinement if atoms on special positions are present. Make sure that atoms on special positions are actually refined in SHELXL as you plan to refine them in the refinement in XHARPy. Use AFIX 1 if hydrogen atoms are located on special positions, but you want to refine them anisotropically in the Hirshfeld refinement or add the ConstraintValues variables manually. As SHELXL cannot refine Gram- Charlier parameters, these need to be added manually for the time being.

Parameters:

filename (str) – Path to the shelxl .lst file

Returns:

constraint_dict – Dictionary containing the generated constraints for the individual atoms and parameters

Return type:

Dict[str, Dict[str, ConstrainedValues]]

xharpy.io.shelxl_hkl2pd(hkl_name: str) → DataFrame

Helper function to read in a shelx-style .hkl file as dataframe. Note that XHARPy does expect a merged hkl file, using an unmerged file will be very slow and lead to unexpected esd values.

Parameters:

hkl_name (str) – Path to hkl file

Returns:

hkl – Dataframe with named columns: ‘h’, ‘k’, ‘l’, ‘intensity’, ‘esd_int’

Return type:

pd.DataFrame

Raises:

ValueError – Number of columns is unexpected for a SHELX hkl file

xharpy.io.site_symm2mat_vec(code: str, symm_mats_vecs: Tuple[ndarray, ndarray]) → Tuple[ndarray, ndarray]

Covert a cif site_symmetry string into the corresponding symmetry matrix and translation vector

Parameters:

  • code (str) – site_symm code from a cif file, e.g. 2_565

  • symm_mats_vecs (Tuple[np.ndarray, np.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

Returns:

  • symm_mat (np.ndarray) – size (3, 3) symmetry matrix

  • trans_vec (np.ndarray) – size (3) array contraining the translation from symmetry and additional translation from code

xharpy.io.split_error(string: str) → Tuple[float, float] | Tuple[int, int]

Helper function to split a string containing a value with error in brackets to a value-esd pair

Parameters:

string (str) – Input string containing the value to be split

Returns:

Pair of floats if a ‘.’ was present in string, otherwise a pair of ints containing the value and its esd

Return type:

Union[Tuple[float, float], Tuple[int, int]]

xharpy.io.symm_to_matrix_vector(instruction: str) → Tuple[jax.numpy.ndarray, jax.numpy.ndarray]

Converts a symmetry instruction into a symmetry matrix and a translation vector for that symmetry element.

Parameters:

instruction (str) – Instruction string containing symmetry instruction for all three coordinates separated by comma signs (e.g -x, -y, 0.5+z)

Returns:

  • symm_matrix (jnp.ndarray,) – size (3, 3) array containing the symmetry matrix for the symmetry element

  • symm_vector (jnp.ndarray) – size (3) array containing the translation vector for the symmetry element

xharpy.io.value_with_esd(values: ndarray, esds: ndarray) → List[str] | str

Create string or strings with the values und estimated standard deviation in the format xxx.xx(y). Will round to 6 digits if esd is nan or zero. Can only handle one-dimensional arrays. So loop outside for use

Parameters:

  • values (np.ndarray) – At maximum a one dimensional array containing the values

  • esds (np.ndarray) – At maximum a one dimensional array containing the esds

Returns:

formatted_strings – string or strings that are formatted according to the style

Return type:

Union[List[str], str]

xharpy.io.write_cif(output_cif_path: str, cif_dataset: str | int, shelx_cif_path: str, shelx_dataset: str | int, cell: jax.numpy.ndarray, cell_esd: jax.numpy.ndarray, symm_mats_vecs: Tuple[jax.numpy.ndarray, jax.numpy.ndarray], hkl: DataFrame, construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, var_cov_mat: jax.numpy.ndarray, refinement_dict: Dict[str, Any], computation_dict: Dict[str, Any], information: Dict[str, Any], source_cif_path: str | None = None, source_dataset: str | int | None = None)

Write a cif file from the given parameters. Currently only works for gpaw and iam refinements.

Parameters:

  • output_cif_path (str) – path where the new cif file is output

  • cif_dataset (Union[str, int]) – name of dataset in cif file

  • shelx_cif_path (str) – Path to the shelx cif used for the refinement. For the time being is used to copy some values, where the calculation is not implemented yet

  • shelx_dataset (Union[str, int]) – dataset within the shelx cif file

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (jnp.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • hkl (pd.DataFrame) – pandas DataFrame containing the reflection data. Needs to have at least five columns: h, k, l, intensity, esd_int, Additional columns will be ignored

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • parameters (jnp.ndarray) – final refined parameters

  • var_cov_mat (jnp.ndarray) – [description]

  • refinement_dict (Dict[str, Any]) – Dictionary with refinement options. For detailed options see refinement function in core

  • computation_dict (Dict[str, Any]) – Dict with options of the to the f0j_source.

  • information (Dict[str, Any]) – Dictionary with additional information, obtained from the refinement. the atomic form factors will be read from this dict.

  • source_cif_path (str, optional) – Additional cif that will be searched for crystal and measurement information. If not given the shelx cif will be tried instead

  • source_dataset (Union[str, int], optional) – Dataset to use in the source_cif

xharpy.io.write_fcf(fcf_path: str, fcf_dataset: str, fcf_mode: int, cell: ndarray, hkl: DataFrame, construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, wavelength: float, refinement_dict: Dict[str, Any], symm_strings: List[str], information: Dict[str, Any]) → DataFrame

Write a fcf file from the results of the refinement for both archival purposes and the visualisation of difference electron densities

Parameters:

  • fcf_path (str) – Path, where the new fcf-file should be written

  • fcf_dataset (str) – Dataset name within the fcf file.

  • fcf_mode (int) – Can be either 4 or 6 at the moment. See SHELXL documentation

  • cell (np.ndarray) – array with the lattice constants (Angstroem, Degree)

  • hkl (pd.DataFrame) – pandas DataFrame containing the reflection data. Needs to have at least five columns: h, k, l, intensity, esd_int, Additional columns will be ignored

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • parameters (jnp.ndarray) – final refined parameters

  • wavelength (float) – Measurement wavelength in Angstroem

  • refinement_dict (Dict[str, Any]) – Dictionary with refinement options. For detailed options see refinement function in core

  • symm_strings (List[str]) – strings containing the symmetry information of the unit cell in the usual cif format

  • information (Dict[str, Any]) – Dictionary with additional information, obtained from the refinement. the atomic form factors will be read from this dict.

Returns:

hkl – DataFrame with additional columns depending on the fcf mode used

Return type:

pd.DataFrame

Raises:

NotImplementedError – Selected a fcf mode, which was not implemented

xharpy.io.write_res(out_res_path: str, in_res_path: str, cell: jax.numpy.ndarray, cell_esd: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, wavelength: float)

Write a SHELXL .res file for visualisation. Will always convert isotropic displacement parameters to the equivalent anistropic ones. Input res is still needed to get the LATT, SYMM and SFAC instructions.

Parameters:

  • out_res_path (str) – Path, where the new .res will be written

  • in_res_path (str) – Input res file to copy some entries. Should also work with a .lst file

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • cell_esd (jnp.ndarray) – array with the estimated standard deviation of the lattice constants (Angstroem, Degree)

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • parameters (jnp.ndarray) – final refined parameters

  • wavelength (float) – Measurement wavelength in Angstroem

xharpy.io.xd_hkl2pd(path: str) → DataFrame

Returns the reflection intensity DataFrame from an XD hkl file. Currently, only F^2 with NDAT 7 is implemented as format

Parameters:

path (str) – Path to hkl file

Returns:

hkl – Dataframe with named columns: ‘h’, ‘k’, ‘l’, ‘dataset’, ‘intensity’, ‘esd_int’, ‘scale’

Return type:

pd.DataFrame

Raises:

NotImplementedError – Format of xd.hkl currently not implemented.

xharpy.paper module

This module contains different functions that were used for the comparisons and plots presented in the paper. I kept them here for reference and in the spirit of open science. However, they were written as custom code for that publication.

xharpy.paper.bench_colors = cycler('color', ['#011671', '#ea5900', '#b10f2e', '#357266', '#e8c547', '#437f97', '#8697e0', '#ffb485', '#f58ea1', '#53b2a0', '#e8d99e', '#93bccc'])

Correction functions with and without q-scaling to apply the correction proposed by Blessing

xharpy.paper.box_options(color, widths=0.35)

Gives back the options for the box plots

xharpy.paper.calc_s12(mat_u1, mat_u2)

Calculates the S12 between the two (3,3) anisotropic displacement matrices

xharpy.paper.calculate_agreement(har_path: str, har_key: str, fcf_path: str, neut_path: str, neut_key: str, rename_dict: Dict[str, str] = {}, adp_conversions: List[Tuple[List[str], ndarray]] = []) → Tuple[Dict[str, Any], DataFrame, DataFrame]

Will generate a comparison between two datasets. The ADPs will be scaled according to Blessing, other parameters are calculated from the fcf and cif files.

Parameters:

  • har_path (str) – Path to the Hirshfeld Atom Refined cif file

  • har_key (str) – Key of the dataset to use within the cif and fcf file given for the HAR dataset

  • fcf_path (str) – Path to the fcf file resulting from the Hirshfeld Atom Refinement

  • neut_path (str) – Path to the neutron cif file

  • neut_key (str) – key of dataset within the neutron cif file

  • rename_dict (Dict[str, str], optional) – If there is a difference between the naming between the two cif files, the naming of the neutron cif will be adapted with key - >value, by default {}

  • adp_conversions (List[Tuple[List[str], np.ndarray]], optional) – If atoms are located on different symmetry equivalent positions this keyword can be used to transform the adps from the neutron cif. For each conversion there needs to be a tuple, where the first entry is a list containing the names of all atoms, where conversion should be applied as strings, the second entry is the symmetry matrix, that converts the neutron position to the HAR position, translation vector is not needed as we only turn the ADPs, by default []

Returns:

  • quality_dict (Dict[str, Any]) – Dictionary with different aggregated quality indicators for the HAR dataset and its comparison to the neutron dataset

  • bond_comparison (pd.DataFrame,) – DataFrame containing the merged distances from both cif files including esd for comparison and plotting

  • adp_comparison (pd.DataFrame) – DataFrame containing the comparison of the ADPs for each individual atom. For the comparison there are three prefixes: ‘nosc’ means no correction according to Blessing, ‘qdel’ means a full correction has been applied, ‘onlydel’ means that no scaling but correction with Delta(Uij) has been applied. Everything is given for reference and comparison. Usually one would use the qdel values.

xharpy.paper.corr_uij_cubic(parameters, uij_neut)
xharpy.paper.corr_uij_cubic_nosc(parameters, uij_neut)
xharpy.paper.corr_uij_hexa(parameters, uij_neut)
xharpy.paper.corr_uij_hexa_nosc(parameters, uij_neut)
xharpy.paper.corr_uij_mono(parameters, uij_neut)
xharpy.paper.corr_uij_mono_nosc(parameters, uij_neut)
xharpy.paper.corr_uij_ortho(parameters, uij_neut)
xharpy.paper.corr_uij_ortho_nosc(parameters, uij_neut)
xharpy.paper.corr_uij_tetra(parameters, uij_neut)
xharpy.paper.corr_uij_tetra_nosc(parameters, uij_neut)
xharpy.paper.corr_uij_tric(parameters, uij_neut)
xharpy.paper.corr_uij_tric_nosc(parameters, uij_neut)
xharpy.paper.figure_height(n_dataset)

Calculate the figure height for the plots in the paer

xharpy.paper.gen_lsq(corr_func: Callable, weights: ndarray) → Callable

Generates a weighted least-squares function for the given correction function and weights

xharpy.paper.plot_heatmap(ax, table, columns, rows, cm, cmap_type='diverging', esds=None)

xharpy.quality module

This module contains functions for calculating quality indicators for a finished refinement.

xharpy.quality.calculate_drk(df: DataFrame, bins: List | int | float = 0.05, equal_sized_bins: bool = False, cell: ndarray | None = None) → Dict[str, Any]

Can calculate a DRK plot for a given pandas DataFrame

Parameters:

  • df (pd.DataFrame) – pandas DataFrame containing the reflection data. Can be either generated by the write_fcf function or generated from a written fcf file by extracting the table with the io.ciflike_to_dict function Expected columns are intensity, esd_int, either a f_calc or a intensity_calc function or the cif equivalents if no column sint/lambda is given the three columns h, k, and l are also needed

  • bins (Union[List, int, float], optional) – Parameter used to define the bins. If it is a float, this is the step size in sin(theta)/lambda, if it is an integer, this is the number of bins the data is supposed to distributed into. By passing a list, the function will use this as inner bin borders, 0 and inf do not need to be given separately, by default 0.05

  • equal_sized_bins (bool, optional) – If true bins needs to be an integer. In that case the binning will create bins with an equal number of reflections instead of an equal range in sin(theta)/lambda, by default False

  • cell (np.ndarray, optional) – size (6) array containing the cell parameters. Needs to be passed if the sint/lambda column is not already in df to calculate the resolution, by default None

Returns:

result_dict – Dictionary with the resulting drk_plots as keys in a dictionary

Return type:

Dict[str, Any]

Raises:

TypeError – The function has encountered an invalid value for bins

xharpy.quality.calculate_egross(fcf_path: str, map_factor: float = 0.3333333333333333) → float

Calculates the e_gross value. Relies on cctbx for the calculation of the difference electron density.

Parameters:

  • fcf_path (str) – Path to the fcf6 file.

  • map_factor (float, optional) – map_factor passed to the fft_map function of cctbx, by default 1/3

Returns:

e_gross – The resulting e_gross value

Return type:

float

xharpy.quality.calculate_quality_indicators(cell: ndarray, symm_mats_vecs: Tuple[ndarray, ndarray], hkl: DataFrame, construction_instructions: List[AtomInstructions], parameters: ndarray, wavelength: float, refinement_dict: Dict[str, Any], information: Dict[str, Any]) → Dict[str, float]

[summary]

Parameters:

  • cell (np.ndarray) – array with the lattice constants (Angstroem, Degree)

  • symm_mats_vecs (Tuple[np.ndarray, np.ndarray]) – (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • hkl (pd.DataFrame) – pandas DataFrame containing the reflection data. Needs to have at least five columns: h, k, l, intensity, esd_int, Additional columns will be ignored

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • parameters (np.ndarray) – final refined parameters

  • wavelength (float) – Measurement wavelength in Angstroem

  • refinement_dict (Dict[str, Any]) – Dictionary with refinement options

  • information (Dict[str, Any]) – Dictionary with additional information, obtained from the refinement. the atomic form factors will be read from this dict.

Returns:

quality_dict – Dictionary with different quality indicators.

Return type:

Dict[str, float]

xharpy.quality.diff_density_values(fcf_path: str, map_factor: float = 0.3333333333333333) → Dict[str, float]

Calculates the rho_max, rho_min and rhos_sigma for a given fcf6 file

Parameters:

  • fcf_path (str) – Path to the fcf6 file.

  • map_factor (float, optional) – map_factor passed to the fft_map function of cctbx, by default 1/3

Returns:

The three value as a dictionary

Return type:

Dict[str, float]

xharpy.quality.generate_hm(fcf_path: str, map_factor: float = 0.3333333333333333, level_step: float = 0.01, level_min: float = -1.0, level_max: float = 1.0) → Dict[str, ndarray]

Generates a Henn-Meindl or normal probability plot from the given fcf6 file. Relies on cctbx for the calculation of the difference electron density.

Parameters:

  • fcf_path (str) – Path to the fcf6 file.

  • map_factor (float, optional) – map_factor passed to the fft_map function of cctbx, by default 1/3

  • level_step (float, optional) – step size in e/Ang^3 for the determination of the Henn-Meindl Plot, by default 0.01

Returns:

results – levels and hm values as dictionary.

Return type:

Dict[str, np.ndarray]

Raises:

  • ModuleNotFoundError – No cctbx installed

  • ValueError – fcf file is probably not fcf6 as it is missing phases

xharpy.refine module

This module contains the core functionality, including the refinement and its analysis from the XHARPy library.

xharpy.refine.calc_f(xyz: jax.numpy.ndarray, uij: jax.numpy.ndarray, cijk: jax.numpy.ndarray, dijkl: jax.numpy.ndarray, occupancies: jax.numpy.ndarray, index_vec_h: jax.numpy.ndarray, cell_mat_f: jax.numpy.ndarray, symm_mats_vecs: Tuple[jax.numpy.ndarray, jax.numpy.ndarray], f0j: jax.numpy.ndarray) → jax.numpy.ndarray

Given a set of parameters, calculate the structure factors for all given reflections

Parameters:

  • xyz (jnp.ndarray) – size (N,3) array of fractional coordinates for the atoms in the asymmetric unit

  • uij (jnp.ndarray) – size (N, 6) array of anisotropic displacement parameters (isotropic parameters have to be transformed to anitropic parameters). Parameters need to be in convention as used e.g. Shelxl or the cif as U. Order: U11, U22, U33, U23, U13, U12

  • cijk (jnp.ndarray) – size (N, 10) array of hird-order Gram-Charlier parameters as defined in Inter. Tables of Cryst. B (2010): Eq 1.2.12.7. Order: C111, C222, C333, C112, C122, C113, C133, C223, C233, C123

  • dijkl (jnp.ndarray) – size (N, 15) array of fourth-order Gram-Charlier parameters as defined in Inter. Tables of Cryst. B (2010): Eq 1.2.12.7. Order: D1111, D2222, D3333, D1112, D1222, D1113, D_1333, D2223, D2333, D1122, D1133, D2233, D1123, D1223, D1233

  • occupancies (jnp.ndarray) – size (N) array of atomic occupancies. Atoms on special positions need to have an occupancy of 1/multiplicity

  • index_vec_h (jnp.ndarray) – size (H, 3) array of Miller indicees of observed reflections

  • cell_mat_f (jnp.ndarray) – size (3, 3) array with the reciprocal lattice vectors (1/Angstroem) as row vectors

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • f0j (jnp.ndarray) – size (K, N, H) array of atomic form factors for all reflections and symmetry generated atoms within the unit cells. Atoms on special positions are present multiple times and have the atomic form factor of the full atom.

Returns:

structure_factors – size (H)-sized array with complex structure factors for each reflection

Return type:

jnp.ndarray

xharpy.refine.calc_lsq_factory(cell_mat_m: jax.numpy.ndarray, symm_mats_vecs: Tuple[jax.numpy.ndarray, jax.numpy.ndarray], index_vec_h: jax.numpy.ndarray, intensities_obs: jax.numpy.ndarray, weights: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], f0j_core: jax.numpy.ndarray, refinement_dict: Dict[str, Any], wavelength: float | None, restraint_instr_ind: List[Any] = []) → Callable

Creates calc_lsq functions that can be used with jax.jit and jax.grad. This way we can account for the very different needs of structures, while keeping the code down the line relatively simple.

Parameters:

  • cell_mat_m (jnp.ndarray) – size (3, 3) array with the cell vectors as row vectors (Angstroem)

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • index_vec_h (jnp.ndarray) – size (H, 3) array of Miller indicees of observed reflections

  • intensities_obs (jnp.ndarray) – size (H) array of observed reflection intensities

  • weights (jnp.ndarray) – size (H) array of weights for the individual reflections

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters

  • f0j_core (jnp.ndarray) – size (N, H) array of atomic core form factors calculated separately

  • refinement_dict (Dict[str, Any]) – Dictionary that contains options for the refinement.

  • wavelength (Optional[float]) – wavelength of radiation used for measurement in Angstroem

  • restraint_instr_ind (List[Any], optional) – List of internal restraint options. Is still very early in development, probably buggy and should not be used for research at the moment, by default []

Returns:

calc_lsq – function that return the sum of least squares for a given set of parameters and atomic form factors

Return type:

Callable

Raises:

NotImplementedError – Core treatment method not implemented

xharpy.refine.calc_var_cor_mat(cell_mat_m: jax.numpy.ndarray, symm_mats_vecs: Tuple[jax.numpy.ndarray, jax.numpy.ndarray], index_vec_h: jax.numpy.ndarray, intensities_obs: jax.numpy.ndarray, weights: jax.numpy.ndarray, construction_instructions: List[AtomInstructions], f0j_core: jax.numpy.ndarray, parameters: jax.numpy.ndarray, f0j: jax.numpy.ndarray, refinement_dict: Dict[str, Any], wavelength: float | None = None) → jax.numpy.ndarray

Calculates the variance-covariance matrix for a given set of parameters At the moment is pretty slow, as it is not parallelised over reflections

Parameters:

  • cell_mat_m (jnp.ndarray) – size (3, 3) array with the cell vectors as row vectors (Angstroem)

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • index_vec_h (jnp.ndarray) – size (H, 3) array of Miller indicees of observed reflections

  • intensities_obs (jnp.ndarray) – size (H) array of observed reflection intensities

  • weights (jnp.ndarray) – size (H) array of weights for the individual reflections

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters

  • f0j_core (jnp.ndarray) – size (N, H) array of atomic core form factors calculated separately

  • parameters (jnp.ndarray) – size (P) array with the refined parameters

  • f0j (jnp.ndarray) – size (K, N, H) array of atomic form factors for all reflections and symmetry generated atoms within the unit cells. Atoms on special positions are present multiple times and have the atomic form factor of the full atom.

  • refinement_dict (Dict[str, Any]) – Dictionary that contains options for the refinement.

  • wavelength (Optional[float], optional) – wavelength of radiation used for measurement in Angstroem, by default None

Returns:

var_cov_mat – size (P, P) array containing the variance-covariance matrix

Return type:

jnp.ndarray

Raises:

  • NotImplementedError – Extinction method not implemented

  • NotImplementedError – Core treatment not implemented

xharpy.refine.refine(cell: jax.numpy.ndarray, symm_mats_vecs: Tuple[jax.numpy.ndarray, jax.numpy.ndarray], hkl: DataFrame, construction_instructions: List[AtomInstructions], parameters: jax.numpy.ndarray, wavelength: float | None = None, refinement_dict: dict = {}, computation_dict: dict = {}) → Tuple[jax.numpy.ndarray, jax.numpy.ndarray, Dict[str, Any]]

Refinement routine. The routine will refine for the given intensities against wR2(F^2).

Parameters:

  • cell (jnp.ndarray) – array with the lattice constants (Angstroem, Degree)

  • symm_mats_vecs (Tuple[jnp.ndarray, jnp.ndarray]) – size (K, 3, 3) array of symmetry matrices and (K, 3) array of translation vectors for all symmetry elements in the unit cell

  • hkl (pd.DataFrame) – pandas DataFrame containing the reflection data. Needs to have at least five columns: h, k, l, intensity, weight. Alternatively weight can be substituted by esd_int. If no weight column is available the weights will be calculated as 1/esd_int**2. Additional columns will be ignored

  • construction_instructions (List[AtomInstructions]) – List of instructions for reconstructing the atomic parameters from the list of refined parameters

  • parameters (jnp.ndarray) – Starting values for the list of parameters

  • wavelength (Optional[float], optional) – Measurement wavelength in Angstroem. Currently only used for Shelxl style extinction correction. Can be omitted otherwise, by default None

  • refinement_dict (dict, optional) –

    Dictionary with refinement options, by default {}

    Available options are:

    • f0j_source: Source of the atomic form factors. The computation_dict will be passed on to this method. See the individual files in f0j_sources for more information, by default ‘gpaw’ Tested options: ‘gpaw’, ‘iam’, ‘gpaw_mpi’ Some limitations: ‘gpaw_spherical’ Still untested: ‘qe’

    • reload_step: Starting with this step the computation will try to reuse the density, if this is implemented in the source, by default 1

    • core: If this is implemented in a f0j_source, it will integrate the frozen core density on a spherical grid and only use the valence density for the updated atomic form factos options are ‘combine’, which will not treat the core density separately, ‘constant’ which will integrate and add the core density without scaling parameter and ‘scale’ which will refine a scaling parameter for the core density which might for systematic deviations due to a coarse valence density grid (untested!) By default ‘constant’

    • extinction: Use an extinction correction. Options: ‘none’ -> no extinction correction, ‘shelxl’ use the (empirical) formula used by SHELXL to correct to correct for extinction, ‘secondary’ see Giacovazzo et al. ‘Fundmentals of Crystallography’ (1992) p.97, by default ‘none’

    • flack: Refinement of the flack parameter. Because xHARPy does not merge at the moment this should not be considered really implemented, by default False

    • max_dist_recalc: If the max difference in atomic positions is under this value in Angstroems, no new structure factors will be calculated, by default 1e-6

    • max_iter: Maximum of refinement cycles if convergence not reached, by default: 100

    • min_iter: Minimum refinement cycles. The refinement will stop if the wR2 increases if the current cycle is higher than min_iter, by default 10

    • core_io: Expects a tuple where the first entry can be ‘save’, ‘load’, ‘none’ which is the action that is taken with the core density. The second argument in the tuple is the filename, to which the core density is saved to or loaded from

    • cutoff: Expects a tuple of three values where the first two are strings and the last one is a float value. First string is a cutoff mode. Currently available are ‘none’ where all reflections are used, ‘sin(theta)/lambda’ where the cutoff is set according to a user given resolution, ‘fraction(f0jval)’ where the resolution cutoff is set to include a certain fraction of the mean absolute valence atomic form factors. ‘I/esd(I)’ can be used for excluding values based on the value over estimated standard deviation The second string can be either be ‘above’ or ‘below’ and denominates in which direction values will be excluded. The final value is the actual cutoff value.

    • restraints: Not fully implemented. Do not use at the moment, by default []

  • computation_dict (dict, optional) – Dict with options that are passed on to the f0j_source. See the individual calc_f0j functions for a more detailed description, by default {}

Returns:

  • parameters (jnp.ndarray) – final refined parameters.

  • var_cov_mat (jnp.ndarray,) – variance covariance matrix of the final refinement step

  • information (Dict[str, Any]) – Dictionary with additional information, some of this is needed for cif output

Raises:

  • NotImplementedError – f0j_source not implemented

  • NotImplementedError – Unknown core description

  • NotImplementedError – Second point where the core description could be missing

xharpy.restraints module

This module is the beginning of a restraint implementation for the XHARPy library. Does not work as it is, and is currently kept as a template for a working implementation.

xharpy.restraints.FixedDistanceRestrInd

alias of DistanceRestrInd

class xharpy.restraints.FixedDistanceRestraint(atom1, atom2, distance, esd)

Bases: tuple

atom1

Alias for field number 0

atom2

Alias for field number 1

distance

Alias for field number 2

esd

Alias for field number 3

class xharpy.restraints.RigidADPRestrInd(atom1_index, atom2_index, esd, mult)

Bases: tuple

atom1_index

Alias for field number 0

atom2_index

Alias for field number 1

esd

Alias for field number 2

mult

Alias for field number 3

class xharpy.restraints.RigidADPRestraint(atom1, atom2, esd, mult)

Bases: tuple

atom1

Alias for field number 0

atom2

Alias for field number 1

esd

Alias for field number 2

mult

Alias for field number 3

class xharpy.restraints.SameADPRestrInd(atom1_index, atom2_index, esd, mult)

Bases: tuple

atom1_index

Alias for field number 0

atom2_index

Alias for field number 1

esd

Alias for field number 2

mult

Alias for field number 3

class xharpy.restraints.SameADPRestraint(atom1, atom2, esd, mult)

Bases: tuple

atom1

Alias for field number 0

atom2

Alias for field number 1

esd

Alias for field number 2

mult

Alias for field number 3

class xharpy.restraints.SameDistanceRestrInd(atom_pair_indexes, esd)

Bases: tuple

atom_pair_indexes

Alias for field number 0

esd

Alias for field number 1

class xharpy.restraints.SameDistanceRestraint(atom_pairs, esd)

Bases: tuple

atom_pairs

Alias for field number 0

esd

Alias for field number 1

xharpy.restraints.create_restraint_instructions(atom_table, restraints)
xharpy.restraints.resolve_restraints(xyz, uij, restraints, cell_mat_m)

xharpy.weighting module

Is meant as the module for handling weights in XHARPy. Currently only contains a function to calculate weights from given parameters.

xharpy.weighting.calc_weights(wght_parameters: jax.numpy.ndarray, c_mode: float, intensity_pos: jax.numpy.ndarray, i_calc: jax.numpy.ndarray, esd_int: jax.numpy.ndarray, sintheta_ov_lambda: jax.numpy.ndarray | None = None) → jax.numpy.ndarray

Calculate weights for given arguments

Parameters:

  • wght_parameters (jnp.ndarray) – size (6) array containing the weight parameters

  • c_mode (float) – in order to be able to call this with derivatives c_mode needs to be called separately

  • intensity_pos (jnp.ndarray) – experimental observed intensities

  • i_calc (jnp.ndarray) – calculated intensities from the refinement

  • esd_int (jnp.ndarray) – estimated standard deviations of the observed intensities

  • sintheta_ov_lambda (jnp.ndarray, optional) – if c_mode != 0 needed sin(theta)/lambda values, by default None

Returns:

weights for the individual reflections

Return type:

jnp.ndarray

Module contents

XHARPy (X-ray diffraction data Hirshfeld Atom Refinement in Python) is a library enabling the refinement against custom non-spherical atomic form factors.