CADISHI compute kernels — CADISHI 1.1.0 documentation

# CADISHI compute kernels

The following documentation was automatically generated from the docstrings present in the source code files.

## cadishi.kernel

Cadishi distance histogram kernels.

## cadishi.kernel.common

Common code used by the Cadishi kernels pydh and cudh.

`cadishi.kernel.common.` `precision_to_enum`(str_id)

  Helper function to translate a string precision identification to the integer identification used inside the kernels PYDH and CUDH.

`cadishi.kernel.common.` `scale_histograms`(np_histos, np_scales)

  Scale histograms with scale factors.

## cadishi.kernel.dist

dist Python interface to c_dist.

Initial implementation of the distance histogram computation using Cython. Legacy code, do not use for production. This code is only used by the test suite to compare the results of (small) problems between the kernels.

`cadishi.kernel.dist.` `histograms`(coordinate_sets, r_max, n_bins)

  Distance histogram calculation on the CPU using Cython kernels.

  Calculate histograms from sets of species coordinates by calling the pwd() and pwd2() CPU functions from the Cython dist_knl. Serves as the reference implementation for the pydh and cudh packages.

  Parameters: | coordinate_sets (list of numpy.ndarray) – List of numpy arrays where each numpy array contains the atom coordinates for all the atoms of a species. r_max (float) – Cutoff radius for the distance calculation. n_bins (int) – Number of histogram bins.
  Returns: | Two-dimensional numpy array containing the distance histograms.
  Return type: | numpy.ndarray

## cadishi.kernel.pydh

pydh Python interface.

Calls the c_pydh Python module.

`cadishi.kernel.pydh.` `distances`(coordinates, precision='single', box=[], force_triclinic=False)

  Driver for the distance calculation functions.

`cadishi.kernel.pydh.` `histograms`(coordinate_sets, r_max, n_bins, precision='single', n_threads=1, blocksize=0, check_input=True, scale_factors=[], mask_array=[], box=[], force_triclinic=False, do_histo2_only=False, verbose=False)

  Distance histogram calculation, Python interface.

  This function is the entry point to run distance histogram calculations from Python on the CPU.

  Parameters: | coordinate_sets (list) – list of double precision numpy arrays [N, 3] containing coordinate triples r_max (float) – maximum distance that should be considered for the histograms n_bins (int) – number of histogram bins precision (string, optional) – String indicating the precision to be used, “single” (default) or “double” n_threads (int, optional) – Number of CPU (OpenMP) threads to be used for the computation, default 1. blocksize (int, optional) – Size of the blocks used to optimize cache usage in units of coordinate tuples. Values around 230 are best to optimize for a L2 cache size of 256 kb. Possible values are: ‘-1’ to disable cache blocking and use naive (old) kernels, ‘0’ to enable blocking and use internal logic to determine the block size (recommended), and positive values to set the block size manually (not recommended, only useful for performance exploration). Note that cache blocking is disabled internally for bin numbers larger than 48000. check_input (bool, optional) – Check the input, i.e. check it the distances fit into the histogram window defined by r_max. Harms performance to some degree but avoids potential memory corruption in case of bogus input. Default is ‘True’. scale_factors (array-like, optional) – Array of floats used to rescale individual histograms after computation. mask_array (array-like, optional) – Array of integers to mask the computation of certain histograms, where ‘0’ indicates that a histogram is skipped. Internal default is all ‘1’. box (array-like, optional) – Periodic box specification. Default is none. force_triclinic (bool, optional) – Use the triclinic box implementation also for simpler orthorhombic boxes. Default is ‘False’. do_histo2_only (bool, optional) – Perform only the inter-species computation in case 2 species are given. Useful for debugging and performance optimization, default is ‘False’. verbose (bool, optional) – Be verbose about internal states during computation. Default is ‘False’.
  Returns: | Column 0 contains the radii, other columns contain the histograms.
  Return type: | NumPy array, double precision

## cadishi.kernel.cudh

cudh Python interface.

Calls the c_cudh Python module.

`cadishi.kernel.cudh.` `get_num_cuda_devices`()

  Get the number of available NVIDIA devices, using the CUDA API.

`cadishi.kernel.cudh.` `get_num_devices`()

  Get the number of available NVIDIA devices.

  We do not use the function “c_cudh.get_num_devices()” because it is not allowed to fork and use CUDA in processes after a first CUDA call, which would be the case in <histograms.py> (and was hard to figure out).

`cadishi.kernel.cudh.` `histograms`(coordinate_sets, r_max, n_bins, precision='single', gpu_id=0, do_histo2_only=False, thread_block_x=0, check_input=True, scale_factors=[], mask_array=[], box=[], force_triclinic=False, verbose=False, algorithm=-1)

  Distance histogram calculation on NVIDIA GPUs using CUDA.

  Calculate distance histograms for sets of species coordinates by calling the CUDA kernels that are provided by the Python module c_cudh written in CUDA.

  Parameters: | coordinate_sets (list of numpy.ndarray) – List of numpy arrays where each numpy array contains the atom coordinates for all the atoms of a species. r_max (float) – Cutoff radius for the distance calculation. n_bins (int) – Number of histogram bins. precision (string, optional) – String specifying the implementation and/or the precision. “single” is the default value for single precision, use “double” for double precision. gpu_id (int, optional) – The GPU to be used to calculate the histograms. 0 is the default value. do_histo2_only (bool, optional) – In case only two sets of coordinates are given, calculate only the distance histogram between the species sets. For benchmark purposes only. thread_block_x (int, optional) – Manually set the CUDA thread block size (x), overrides the internal default if set to a value larger than zero. For benchmark and debugging purposes.
  Returns: | Two-dimensional numpy array containing the distance histograms.
  Return type: | numpy.ndarray