hikari.scripts package

Submodules

hikari.scripts.angular_explorer module

This file contains tools for making property maps visualised on sphere

class hikari.scripts.angular_explorer.AngularPotencyExplorer

Bases: AngularPropertyExplorer

explore()

Main interface method which, apart from the setters, is run within the script itself and generates data and figures using class methods

hkl_is_read_not_generated: bool = False
property_name: str = 'potency'
property_theoretical_limits: Interval = Interval(0, 1)
class hikari.scripts.angular_explorer.AngularPropertyExplorer

Bases: object

An abstract base class for objects handling analysing parameters as a function of crystal orientation in a Diamond Anvil Cell. In order to generate a map of desired property, the following methods must be executed in order:

  • set_path

  • set_sample

  • set_output

  • explore

AZIMUTH_LIMIT_DICT = {<System.triclinic: 0>: Interval(-45, 135), <System.monoclinic: 1>: Interval(0, 90), <System.orthorhombic: 2>: Interval(0, 90), <System.tetragonal: 4>: Interval(0, 90), <System.trigonal: 3>: Interval(0, 120), <System.hexagonal: 6>: Interval(0, 120), <System.cubic: 5>: Interval(0, 90)}
GNUPLOT_INPUT_EXTENSION = '.gnu'
GNUPLOT_OUTPUT_EXTENSION = '.pnG'
HISTOGRAM_EXTENSION = '.his'
HKL_EXTENSION = '.hkl'
LISTING_EXTENSION = '.lst'
MATPLOTLIB_EXTENSION = '.png'
MESH_EXTENSION = '.dat'
POLAR_LIMIT_DICT = {<System.triclinic: 0>: Interval(0, 180), <System.monoclinic: 1>: Interval(0, 180), <System.orthorhombic: 2>: Interval(0, 90), <System.tetragonal: 4>: Interval(0, 90), <System.trigonal: 3>: Interval(0, 90), <System.hexagonal: 6>: Interval(0, 90), <System.cubic: 5>: Interval(0, 90)}
property angle_res
property descriptive_statistics_string
draw_gnuplot_map()
draw_matplotlib_map()
abstract explore()

Main interface method which, apart from the setters, is run within the script itself and generates data and figures using class methods

property focus_cartesian
property focus_spherical_closest
hkl_is_read_not_generated: bool
property lg
orientation_weights(th, ph)

Calculate how much each point should contribute to distribution

property path

Provides path = directory + stem to the workspace. They are common to all input and output files, the extensions are specified as class var.

property pg
property ph_comb
property ph_limits

Interval range of azimuth angle where property will be calculated

property ph_mesh
property ph_range
property prop_at_focus_closest
property prop_at_focus_string
property prop_limits
property_name: str
property_theoretical_limits: Interval
set_up(a, b, c, al, be, ga, space_group, wavelength, axis, opening_angle, orientation, resolution, path, fix_scale, histogram, output_quality)
property sg
property th_comb
property th_limits

Interval range of polar angle where property will be calculated

property th_mesh
property th_range
write_hist_file()
class hikari.scripts.angular_explorer.AngularPropertyExplorerFactory

Bases: object

A factory method for creating angular property explorers.

create(prop, **kwargs)
register(prop, explorer)
class hikari.scripts.angular_explorer.AngularR1Explorer

Bases: AngularPropertyExplorer

explore()

Main interface method which, apart from the setters, is run within the script itself and generates data and figures using class methods

hkl_is_read_not_generated: bool = True
property_name: str = 'R1'
property_theoretical_limits: Interval = Interval(0, 1)

hikari.scripts.compare_adps module

hikari.scripts.compare_adps.animate_similarity_index(u_diag, transformations, output_path)

Make a gif presenting the change of similarity index against some arbitrary series of transformations. Initial displacement matrix must be diagonal, values given in u_diag, evaluated against a regular unit cell with a = 1.

Parameters

  • u_diag (Iterable) – triplet of u matrix diagonal elements

  • transformations (List[ndarray]) – list of transformations to be plotted every 0.1 sec

  • output_path (str) – path where resulting gif file will be saved

Return type

None

hikari.scripts.compare_adps.calculate_similarity_indices(cif1_path, cif2_path=None, cif1_block=None, cif2_block=None, output_path=None, normalize=False, uncertainties=True)

Compare Anisotropic Displacement Parameters of all atoms in two cif blocks and return a Similarity Index (SI) for these pairs of atoms that exist and are defined anisotropic (via “_atom_site_aniso_U_**”) in both files.

This script requires two independent cif blocks to run, but the location of both blocks can be specified in multiple ways:

  • If only cif1_path is given, the first and second data block from cif1 file will be used in SI evaluation;

  • If cif1_path and cif2_path are given, the first data block from each cif file will be used instead;

  • If cif1_path, cif2_path, and cif1_block are given, cif1_block from each cif1_path and cif2_path cif files will be used.

  • If cif1_path, cif2_path, cif1_block, and cif2_block are given, cif1_block in cif1_path and cif2_block in cif2_path will be used.

For a single cif file ‘glycine.cif’ with two data blocks named ‘100K’ and ‘RT’, the three following commands will have the same effect:

Example

Parameters

  • cif1_path (str) –

  • cif2_path (Optional[str]) –

  • cif1_block (Optional[str]) –

  • cif2_block (Optional[str]) –

  • output_path (Optional[str]) –

  • normalize (bool) –

  • uncertainties (bool) –

Return type

None

>>> calculate_similarity_indices('glycine.cif')
>>> calculate_similarity_indices('glycine.cif', 'glycine.cif')
>>> calculate_similarity_indices('glycine.cif', 'glycine.cif', '100K', 'RT')

For two cif files ‘X-rays.cif’ and ‘neutrons.cif’ with data block named ‘RT’ and ‘100K’ (one each), the two following commands will have the same effect:

Example

Parameters

  • cif1_path (str) –

  • cif2_path (Optional[str]) –

  • cif1_block (Optional[str]) –

  • cif2_block (Optional[str]) –

  • output_path (Optional[str]) –

  • normalize (bool) –

  • uncertainties (bool) –

Return type

None

>>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif')
>>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif', 'RT', '100K')

The behaviour of script can be further altered via other parameters. If output_file is set True, the results will be written there instead of console. If uncertainties is set True, standard deviations of all ADPs as well as the unit cell parameters from 1st cif file will be assumed uncorrelated and used to estimate the uncertainty of every SI determination.

For more information about Similarity Index (SI) itself, please consult Whitten and Spackman, Acta Cryst B 62, 875 (2006) https://doi.org/10.1107/S0108768106020787.

Parameters

  • cif1_path (str) – Absolute or relative path to the first cif file.

  • cif2_path (Optional[str]) – Absolute or relative path to the second cif file. If not specified, it is assumed equal to cif1_path.

  • cif1_block (Optional[str]) – Name of the first data block used in SI determination. It points to the data block inside the file specified by cif1_path. If not specified, the first block found in said file will be used.

  • cif2_block (Optional[str]) – Name of the second data block used in SI determination. It points to the data block inside the file specified by cif2_path. If not specified, the first unused block in said file will be used.

  • output_path (Optional[str]) – Path where the output of the program should be written.

  • uncertainties (bool) – If True, propagate the standard deviations of individual ADPs’ and cif1’s unit cell to estimate SI’s uncertainties.

  • normalize (bool) – If True, equalize the volume of displacement ellipsoids by normalizing the determinants of ADP matrices expressed in cartesian coordinates. As a result, SI is a function of displacement “shape” only.

Return type

None

hikari.scripts.fcf module

hikari.scripts.fcf.baycon_plot(x_key='ze', y_key='si', a=10.0, b=10.0, c=10.0, al=90.0, be=90.0, ga=90.0, input_path='shelx.fcf', input_format='shelx_fcf', input_wavelength='MoKa', output_path='baycon.png')

For a given .fcf file prepare a bayesian conditional probability plot between x_key and y_key.

Parameters

  • x_key (str) – Parameter of HklFrame which will be placed on x axis

  • y_key (str) – Parameter of HklFrame which will be placed on x axis

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • input_path (str) – Path to the input .fcf file.

  • input_format (int or str or dict) – Format of the input .fcf file. For reference see hikari.dataframes.HklFrame.interpret_hkl_format().

  • input_wavelength (float or str) – Wavelength of radiation utilised in experiment.

  • output_path (str) – Path to the output .png file.

hikari.scripts.fcf.calculate_sample_form_factors(a, b, c, al, be, ga, space_group, res_path)

Estimate and print selected IAM XRD form factors for given crystal structure

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • space_group (str or int) – Short Hermann-Mauguin name or index of space group. For details see table in hikari.symmetry.space_groups.

  • res_path (str) – Absolute or relative path to the input .res file.

Returns

None

Return type

None

hikari.scripts.fcf.fcf_descriptors(input_path='shelx.fcf', input_format='shelx_fcf')
hikari.scripts.fcf.normal_probability_plot(input_path='shelx.fcf', input_format='shelx_fcf', output_path='Io_vs_Ic.png')
hikari.scripts.fcf.observed_vs_calculated_plot(input_path='shelx.fcf', input_format='shelx_fcf', output_path='Io_vs_Ic.png')

hikari.scripts.hkl_completeness module

This sub-module contains scripts made to work mainly with .hkl files, containing information from single crystal diffraction experiments. Due to authors interest in the subjects, majority of them aim to analyse or model data from high-pressure experiments, which utilise DAC - diamond anvil cell.

hikari.scripts.hkl_completeness.completeness_statistics(a, b, c, al, be, ga, space_group='P-1', input_path='shelx.hkl', input_format='shelx_4', input_wavelength='CuKa')

For a given experimental .hkl file calculate basic completeness statistics in ten resolution shells of equal-volume.

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • space_group (str or int) – Short Hermann-Mauguin name or index of space group. For details see table in hikari.symmetry.space_groups.

  • input_path (str) – Path to the input .hkl file.

  • input_format (str or dict) – Format of the .hkl file. For reference see hikari.dataframes.HklFrame.interpret_hkl_format().

  • input_wavelength (float or str) – Wavelength of radiation utilised in experiment.

Returns

None

Return type

None

hikari.scripts.hkl_completeness.dac_statistics(a, b, c, al, be, ga, space_group='P1', opening_angle=35.0, orientation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), input_path='shelx.hkl', input_format=4, input_wavelength='CuKa', resolution=None)

For a given experimental .hkl file calculate number of experimentally found and theoretically possible reflections up to a given resolution.

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • space_group (str or int) – Short Hermann-Mauguin name or index of space group. For details see table in hikari.symmetry.space_groups.

  • opening_angle (float) – Value of single opening angle as defined in hikari.dataframes.HklFrame.dac().

  • orientation (tuple or numpy.array) – Crystal orientation as defined in hikari.dataframes.BaseFrame

  • input_path (str) – Path to the input .hkl file.

  • input_format (int or str or dict) – Format of the .hkl file. For reference see hikari.dataframes.HklFrame.interpret_hkl_format().

  • input_wavelength (float or str) – Wavelength of radiation utilised in experiment.

  • resolution (float) – If given, calculate statistics only up to this value. Please provide it as a distance in rec. space (twice the resolution in A-1).

Returns

None

hikari.scripts.hkl_completeness.reformat_hkl(input_path, input_format, output_path, output_format)
Parameters

  • input_path (str) – Relative or absolute path to the input .hkl file.

  • input_format (str) – Format of the .hkl file. For reference see hikari.dataframes.HklIo.format.

  • output_path (str) – Relative or absolute path to the output .hkl file.

  • output_format (str) – Format of the .hkl file. For reference see hikari.dataframes.HklIo.format.

Returns

Return type

hikari.scripts.hkl_completeness.simulate_dac(a, b, c, al, be, ga, opening_angle=35, orientation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), vector=None, resolution=None, input_path='shelx.hkl', input_format=4, input_wavelength='CuKa', output_path='output.hkl', output_format=4)

For a given experimental .hkl file simulate a lack of completeness caused by a presence of high-pressure diamond anvil cell.

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • opening_angle (float) – Value of single opening angle as defined in hikari.dataframes.HklFrame.dac().

  • orientation (tuple or numpy.array) – Crystal orientation as defined in hikari.dataframes.BaseFrame

  • vector (tuple) – If given, overwrite orientation to provide information about crystal placement in dac, as defined in hikari.dataframes.HklFrame.dac().

  • resolution (float) – If given, additionally limit data resolution to given value. Please provide the resolution as a distance from the origin in reciprocal space (twice the resolution in reciprocal angstrom).

  • input_path (str) – Path to the input .hkl file.

  • input_format (int or str or dict) – Format of the input .hkl file. For reference see hikari.dataframes.HklFrame.interpret_hkl_format().

  • input_wavelength (float or str) – Wavelength of radiation utilised in experiment.

  • output_path (str) – Path to the output .hkl file.

  • output_format (int or str or dict) – Format of the input .hkl file. For reference see hikari.dataframes.HklFrame.interpret_hkl_format().

Returns

None

hikari.scripts.hkl_potency module

hikari.scripts.hkl_potency.dac_potency_around_axis(a, b, c, al, be, ga, space_group='P1', opening_angle=35.0, wavelength='MoKa', vector=(1, 0, 0), topple_angle=5)

For a given crystal, opening angle, and wavelength calculate average potency obtained by toppling the crystal by “topple_angle”° from the “vector” axis.

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter beta in degrees.

  • ga (float) – Unit cell parameter gamma in degrees.

  • space_group (str or int) – Short Hermann-Mauguin name or index of space group. For details see hikari.symmetry.space_groups.

  • wavelength (float or str) – Wavelength of radiation utilised in experiment.

  • opening_angle (float) – Value of single opening angle as defined in hikari.dataframes.HklFrame.dac().

  • vector (tuple) – Direction from which a theoretical crystal will be toppled.

  • topple_angle (float) – Angle by which theoretical crystal will be toppled.

Returns

None

hikari.scripts.hkl_potency.potency_map(a, b, c, al, be, ga, space_group='P1', axis='', fix_scale=False, histogram=True, opening_angle=35, orientation=None, path='~/sortav.lst', output_quality=3, resolution=1.2, wavelength='MoKa')

Calculate and draw a potency map for a given crystal in diamond anvil cell (DAC) with a given opening angle, as a function of crystal orientation. For details see this paper.

The script accepts unit cell & space group information, and predicts max completeness of fully merged data for investigated crystal in said group. Results are logged into text files and drawn with gnuplot or matplotlib.

Potency is calculated and visualised on a unit-sphere orientation heatmap. Each point p is associated with a certain crystal orientation in DAC, such that vector v from 0 to p acts as a symmetry axis for the dac-accessible volume traced in the reciprocal space up to resolution. Red / green / blue vectors represent crystallographic directions X*, Y* and Z*, respectively. Since the distribution has some inherent symmetry, only a representative part of sphere (usually an octant) is shown.

As an example, let’s assume a orthorhombic cell with a = b = c = 10 and laue group “mmm”. Running the script and generating the potency the map yields the lowest values close to X*, Y* and Z* vector, while the highest values are observed between those vectors. Placing the crystal on its [100] face inside the dac will cause the dac-accessible plane to be placed perpendicularly to (100) direction in reciprocal space. Since the values close to X* ((100) direction) are low, such a placement will allow us to collect data with low coverage. On the other hand, placing the crystal on its [111] face will cause the dac-accessible plane to be placed perpendicularly to (100) direction in reciprocal space. As on the sphere the values tend to rise the further we are from of X*, Y* and Z*, we expect this crystal orientation to warrant a high completeness of collected data.

The potency is calculated as a ratio of the number of unique reflections inside the DAC-accessible space to the number of unique reflections inside a reference sphere of a radius equal to resolution. Visualisation is performed using an extended rainbow heatmap, which utilises a wide color range to emphasize even small differences. Dy default, the color scale is dynamic and adapts to the range of calculated potency, but it can be fixed to 0-100% range using fix_scale=True.

Since the orientation is given in spherical coordinates, the exact positions of individual points is given using theta and phi angles instead of crystallographic coordinates. The theta and phi angles here follow the physical definition (ISO 80000-2:2019). For a given DAC-axis vector v:

  • theta is the azimuth angle found between vector Z* and v. It can assume values between zero and pi (pi/2 in one octant).

  • phi is the rotational angle denoting rotation of v around Z*. It can assume values between zero and 2 pi (pi/2 in one octant).

Finally it must be noted that higher potency setting is not always better. For example, for opening angle below 45 degrees, most potent orientation in laue class mmm renders all 0kl, h0l, hk0 reflections inaccessible. Potency map should be consulted before a high-pressure experiment, but it should not be treated as an universal quality indicator of given set-up.

Parameters

  • a (float) – Unit cell parameter a in Angstrom.

  • b (float) – Unit cell parameter b in Angstrom.

  • c (float) – Unit cell parameter c in Angstrom.

  • al (float) – Unit cell parameter alpha in degrees.

  • be (float) – Unit cell parameter alpha in degrees.

  • ga (float) – Unit cell parameter alpha in degrees.

  • space_group (str or int) – Short Hermann-Mauguin name or index of space group. For details see hikari.symmetry.space_groups.

  • axis (string) – domain to calculate potency in. Accepts ‘x’/ ‘y’/ ‘z’ for h00/ 0k0/ 00l, ‘xy’/’xz’/’yz’ for hk0/ h0l/ 0kl, or ‘’ for all reflections.

  • fix_scale (bool) – If true, the colour scheme will fix to 0 - 100% range.

  • histogram (bool) – If true, potency distribution will be plotted as histogram

  • opening_angle (float) – Value of single opening angle as defined in hikari.dataframes.HklFrame.dac().

  • orientation (np.ndarray) – either a cif-style 3x3 matrix of crystal orientation or a 3-length array with a diamond-perpendicular face to be marked on a map

  • path (str) – Path to a file where script is to be run. Extension is ignored, but file name will and must be the same for all input and output files.

  • output_quality (int) – Density of individual orientations to be considered. Should be in range from 1 (every 15 degrees) to 5 (every 1 degree).

  • resolution (float) – Upper limit of reflection resolution, given as a distance from zero to node in reciprocal space (one over plane spacing) in A-1.

  • wavelength (float or str) – Wavelength of radiation to be simulated.

Returns

None

Return type

None

hikari.scripts.hkl_potency.potency_violin_plot(job_name='violin', directory='~', opening_angle=35, precision=1000, space_groups=('P-1', 'P2/m', 'Pmmm', 'P4/m', 'P4/mmm', 'P-3', 'P-3m1', 'P6/m', 'P6/mmm', 'Pm-3', 'Pm-3m'), labels=('$\\overline{1}$', '$2/m$', '$mmm$', '$4/m$', '$4/mmm$', '$\\overline{3}$', '$\\overline{3}m$', '$6/m$', '$6/mmm$', '$m\\overline{3}$', '$m\\overline{3}m$'), resolution=None, wavelength='MoKa')

Calculate potency distribution for selected space groups and multiple sample orientations in a DAC, log it, and (re)draw appropriate violin plot.

Parameters

  • job_name (str) – Base name for created files, defaults to ‘violin’. If a .csv file with this name already exists, redraw instead of calculating.

  • directory (str) – Target directory for saving or reading, defaults to ‘~’.

  • opening_angle (float) – Value of single opening angle as defined in hikari.dataframes.HklFrame.dac(). Defaults to 35.

  • precision (int) – Number of orientations to investigate, defaults to 1000.

  • space_groups (Tuple[int] or Tuple[str]) – List of space groups to investigate, strings or ints (see hikari.symmetry.Group). Defaults to 11 “Laue” groups.

  • labels (Tuple[str]) – List of tex-style labels to be used for logging and plotting.

  • resolution (float) – If given, additionally limit data resolution to given value. Please provide the resolution as a distance from the origin in reciprocal space (twice the resolution in reciprocal angstrom).

  • wavelength (float or str) – Wavelength of radiation to be simulated.

Returns

None

Return type

None

hikari.scripts.hkl_potency.potency_vs_dac_opening_angle(output_path='~/output.txt', precision=91, resolution=1.2, wavelength='MoKa', theta=None)

Calculate potency in P1 space group as a function of DAC opening angle, assuming certain resolution and wavelength used.

Parameters

  • output_path (str) – Path of created file containing calculated data.

  • precision (int) – Number of probed opening angles between 0 and 90 degrees.

  • resolution (float) – Maximum distance from the origin in reciprocal space to reflection (twice the resolution in reciprocal angstrom). Default 1.2.

  • wavelength (float or str) – Wavelength of radiation to be simulated.

  • theta (float) – If given, use max theta in degrees (instead of radius in A-1).

Returns

None

hikari.scripts.r1_map module

hikari.scripts.r1_map.r1_map(a, b, c, al, be, ga, space_group='P1', axis='', fix_scale=False, histogram=True, opening_angle=35, orientation=None, path='~/sortav.lst', output_quality=3, resolution=1.2, wavelength='MoKa')

Calculate and draw a r1 map for a given crystal in diamond anvil cell (DAC) with a given opening angle, as a function of crystal orientation.

The script accepts unit cell & space group information, runs SHELXL, and reads value of R1 after single refinement. Results are logged into text files and drawn with gnuplot or matplotlib, depending on settings.

For further detail concerning r1_map, its basis and uses, refer to hikari.scripts.potency_map(), as well as selected terminology described in this paper.

Module contents

This module contains all major scripts of hikari. A script is a high-level hikari function, which utilises a lot of low-level objects such as hikari hikari.dataframe or hikari.symmetry in order to provide more sophisticated functionality.

Since HklFrame is the most developed hikari.dataframe of hikari, majority of existing scripts revolve about modification of the .hkl file. It should be mentioned that writing a hikari script does require elemental knowledge of other objects within the package, but should not be a problem after a short study of code.

Users are cordially invited to propose their own scripts or script ideas.