Core

This submodule contains the core functions for the atom_access package, and primarily contains convenience functions for the calculation of a ray trace through a set of atoms, and the clustering of rays.

In particular, the trace_rays function is used to calculate the intersection of a set of rays with a set of atoms, and the cluster_rays function is used to cluster the rays based on their intersection points.

This submodule contains the core atom_access functionality

atom_access.core.cluster_rays(rays: list[Ray], zcw_density: int) → list[int]

Clusters rays based on adjacency/connectivity to neighbour. ZCW Density defines distance between nearest neighbour rays generated in ZCW algorithm - similar to the use of atomic radii in molecular connectivity graphs.

Parameters:

rays (list[Ray]) – Rays to cluster as atom_access.objects.ray objects
zcw_density (int) – Value indicating density of rays generated using Zaremba-Conroy-Wolfsberg algorithm.

Returns:

Integers specifying which cluster each ray belongs to

Return type:

np.ndarray[int]

Calculate the size of each cluster in terms of % solid angle.

Parameters:

cluster_id (np.ndarray[int]) – Integers specifying which cluster each ray belongs to
total_rays (int) – Total number of rays generated using Zaremba-Conroy-Wolfsberg algorithm.

Returns:

list[float] – % solid angle of each cluster, ordered from largest to smallest cluster
list[int] – Integers specifying ordering (l->s) of cluster percentages relative to initial cluster_id order

atom_access.core.generate_output(f_head: str, zcw_density: int, pc_unblocked: float, clust_percent: list[float], radial_cutoff: float, no_header: bool = False) → None

Generate an output file with molecule name, settings and cluster sizes.

Parameters:

f_head (str) – Input .xyz file name without .xyz extension
zcw_density (int) – Value indicating density of rays generated using Zaremba-Conroy-Wolfsberg algorithm.
pc_unblocked (float) – Total % of unblocked rays
clust_percent (list[float]) – Size of each cluster given as % solid angle, ordered from largest to smallest cluster.
radial_cutoff (float) – Cutoff after which atoms will not be considered in raytracing
no_header (bool) – True if header suppressed in output file

Return type:

None

atom_access.core.neighbours(rays: list[Ray], n: int, threads: int) → float

Calculates maximum nth-nearest neighbour distance for a group of rays.

Parameters:

rays (list[Ray]) – List of atom_access.objects.rays generated using ZCW algorithm
n (int) – Index of requested (nth) nearest neighbour
threads (int) – Number of threads to parallelise over

Returns:

maximum distance between any ray and its nth nearest neighbour

Return type:

float

atom_access.core.trace_rays(labels: list[str], coords: ndarray[tuple[int, ...], dtype[_ScalarType_co]], centre: int, radial_cutoff: float, zcw_density: int) → tuple[list[Ray], list[Ray], int]

Performs ray tracing calculation on set of atomic coordinates to find blocked and unblocked rays, identifying which spheres the rays are blocked by. Atoms within radial_cutoff distance from the centre are represented by spheres with van der Waals atomic radii. Rays emanate from centre and are blocked by intersection with an atom.

For van der Waals radii see:: CRC Handbook of Chemistry and Physics, 97th Ed.; W. H. Haynes Ed. CRC Press/Taylor and Francis: Boca Raton, 2016 (accessed 2020-10-01).

Parameters:

labels (list[str]) –
Atomic labels. Non-atomic centres with radius 0 can be specified with

a label of Z
coords (np.ndarray[float]) – (n_atoms,3) array containing xyz coordinates of each atom
centre (int) – Index of central atom from which rays emanate
radial_cutoff (float) – Cutoff after which atoms will not be considered in raytracing
zcw_density (int) – Value indicating density of rays generated using Zaremba-Conroy-Wolfsberg algorithm.

Returns:

list[Ray] – Blocked rays as atom_access.objects.ray objects
list[Ray] – Unblocked rays as atom_access.objects.ray objects
int – Number of atoms excluded by radial_cutoff