assign_atoms_to_grid

mdtools.structure.assign_atoms_to_grid(ag, nbins=None, binwidth=None, bins=None, discard_below=False, discard_above=False, expand_binnumbers=False, box=None, assume_wrapped=False, return_bins=False, return_ag=False)[source]

Assign Atoms to grid points.

Divide the simulation box into given subvolumes and assign each atom of the given MDAnalysis AtomGroup to its corresponding grid point based on its spatial position. Be aware of the ambiguous nomenclature: Actually, the atoms are not assigned to the points/nodes of the grid but to the subvolumes that are spanned by the grid.

The grid spacing can be specified by either nbins, binwidth or bins. You must provide exactly one of the three arguments.

If nbins is given, each spatial dimension will be divided into the given number of equidistant bins ranging from 0 to the corresponding box length.

If binwidth is given, each spatial dimension will be divided into equidistant bins of the given width ranging from 0 to the corresponding box length. If binwidth is not a multiple of the corresponding box length, there will be a thin box region (thinner than binwidth) that is beyond the bounds of the created bins.

With bins you can provide arbitrary bin edges for each spatial dimension with the only limitation that the bin edges must lie within the simulation box. The given bin edges will be sorted in increasing order and duplicate entries will be removed.

Parameters:

ag (MDAnalysis.core.groups.AtomGroup) – MDAnalysis AtomGroup or, UpdatingAtomGroup whose Atoms should be assigned to the given grid points.
nbins (int or sequence of ints or None, optional) – Number of bins (not bin edges!) to use in each spatial dimension. You can provide either one integer for each spatial dimension or a single integer that is used for all spatial dimensions. Must not be used together with binwidth or bins.
binwidth (scalar or sequence of scalars or None, optional) – The bin width to use in each spatial dimension. You can provide either one bin width for each spatial dimension or a single bin width that is used for all spatial dimensions. Must not be used together with nbins or bins.
bins (array_like or sequence of array_likes or None, optional) – Array of bin edges to use in each spatial dimension. You can provide either one array of bin edges for each spatial dimension or a single array that is used for all spatial dimension. Must not be used together with nbins or binwidth.
discard_below, discard_above (bool, optional) – If True, discard atoms that lie below/above the first/last bin edge in each dimension. If False, an extra, infinite bin is created below/above the first/last bin edge in each dimension to capture atoms that lie beyond these bin edges. That means if both, discard_below and discard_above, are False, the number of bins in a given dimension is len(bins) + 1 (here, bins is the returned array of bin edges for a given dimension). If one of them is True, the number of bins is len(bins). If both are True, the number of bins is len(bins) - 1. In all cases, bin numbering starts at 0.

Generally, atoms that lie beyond the first/last bin edge are assigned to bin number 0/len(bins) for the corresponding dimension (see mdtools.numpy_helper_functions.digitize_dd()). If discard_below/discard_above is True all atoms that got assigned such a bin number are discarded and these bin numbers are deleted from the output array bin_ix. Note that in the case of discard_below, bin_ix gets subsequently subtracted by 1 so that bin numbering starts again at 0 (but now 0 is the first valid bin with bin edges [bins[0], bins[1]) in the corresponding dimension).
expand_binnumbers (bool, optional) – If True, the returned index array is unraveled into an array of shape (D, N) where each row gives the bin numbers of all N atoms along the corresponding dimension D. If False, the returned index array has shape (N,) and maps each atom to its corresponding linearized bin number (using row-major ordering). Whether the linearized bin indices index into an array containing the extra, infinite bins at the outer bin edges depends on the value of discard_below and discard_above. See also mdtools.numpy_helper_functions.digitize_dd().
box (array_like, optional) – The unit cell dimensions of the system, which must be provided in the same format as returned by MDAnalysis.coordinates.timestep.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma]. If None, the dimensions of the current Timestep are used. This function can only handle orthogonal simulation boxes.
assume_wrapped (bool, optional) – If True, the Atoms of the input AtomGroup are assumed to be already wrapped into the primary unit cell. If False this will be done before assigning them to their grid points.
return_bins (bool, optional) – If True, return the used bin edges for each dimension.
return_ag (bool, optional) – If True, return an MDAnalysis AtomGroup containing the “valid” Atoms. An atom is “invalid” if it lies below/above the last bin edge and discard_below/discard_above is True. If both, discard_below/discard_above, are False, there are no “invalid” atoms.

Returns:

bin_ix (numpy.ndarray) – Array of indices. This array assigns to each “valid” Atom> of the input AtomGroup an integer that represents the bin number to which this atom belongs. The representation depends on the expand_binnumbers argument. Atoms are “invalid” if they lie below/above the last bin edge and discard_below/discard_above is True.
bins (tuple of numpy.ndarrays) – Tuple of 1-dimensional arrays containing the bin edges used for each dimension. Only returned if return_bins is True.
atoms (MDAnalysis.core.groups.AtomGroup) – MDAnalysis AtomGroup containing the “valid” Atoms. If both, discard_below and discard_above, are False, this is the same as the input AtomGroup. Only returned if return_ag is True.