molsysmt.structure.get_distances#

molsysmt.structure.get_distances(molecular_system, selection='all', structure_indices='all', center_of_atoms=False, weights=None, molecular_system_2=None, selection_2=None, structure_indices_2=None, center_of_atoms_2=False, weights_2=None, pairs=False, pbc=True, output_type='numpy.ndarray', output_indices=None, output_structure_indices=None, engine='MolSysMT', syntax='MolSysMT', heavy_mode='auto', use_gpu=None, parallel=None, num_threads=None, skip_digestion=False)[source]#

Computing distances between atoms or centers of selections.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • center_of_atoms (bool, default=False) – Whether to compute distances relative to geometric centers.

  • weights (numpy.ndarray, list, or tuple, default=None) – Atomic mass weights array for center calculation.

  • molecular_system_2 (molecular system or None, default=None) – Second molecular system to compare with the first one.

  • selection_2 (str, list, tuple, or numpy.ndarray, default=None) – Second selection string or boolean/integer array.

  • structure_indices_2 (int, list, tuple, or numpy.ndarray, default=None) – Structure indices (0-based) for the second selection.

  • center_of_atoms_2 (bool, default=False) – Whether to compute distances relative to geometric centers for selection_2.

  • weights_2 (numpy.ndarray, list, or tuple, default=None) – Atomic mass weights array for selection_2.

  • pairs (bool, default=False) – Whether corresponding selections define explicit pairs instead of a Cartesian product.

  • pbc (bool, default=True) – Whether to take periodic boundary conditions into account.

  • output_type (str, default='numpy.ndarray') – Representation used for the returned result.

  • output_indices ({'selection', 'atom', 'group'} or None, default=None) – Index convention included with the returned values.

  • output_structure_indices ({'selection', 'structure'} or None, default=None) – Structure-index convention included with the returned values.

  • engine (str, default='MolSysMT') – Backend used to perform the calculation.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • heavy_mode ({'auto', 'force', 'off'}, default='auto') – Policy controlling the chunked path for memory-intensive calculations. Coordinate and box blocks use nm internally; the result retains its length unit independently of session standard units.

  • use_gpu (bool, default=None) – Whether to perform computation using GPU acceleration.

  • parallel (bool or None, default=None) – Whether to use CPU parallelism, or None to use the configured default.

  • num_threads (int or None, default=None) – Number of CPU worker threads, or None to use the configured default.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

Distances with shape (n_structures, n_selection[, n_selection_2]) or structured dictionaries, depending on output_type.

Return type:

numpy.ndarray or dict

Raises:

NotImplementedMethodError – If a requested path/output is not supported.

Notes

  • Uses minimum image convention when pbc=True and box is available.

  • When pairs=True, expects explicit pairs; otherwise Cartesian products of selections are used.

Added in version 1.0.0.

On this page