molsysmt.structure.shift_dihedral_angles#

molsysmt.structure.shift_dihedral_angles(molecular_system, dihedral_quartets=None, shifts=None, blocks=None, structure_indices='all', pbc=True, in_place=False, engine='MolSysMT', skip_digestion=False)[source]#

Shift (increment/decrement) dihedral angles by specified amounts.

Reads the current dihedral angles with get_dihedral_angles, adds the requested shifts, and writes the result back with set_dihedral_angles. All covalent-block detection and PBC handling are delegated to set_dihedral_angles.

Parameters:

  • molecular_system (molecular system) – Input system in any form supported by MolSysMT.

  • dihedral_quartets (list, tuple or numpy.ndarray of shape (n_quartets, 4)) – Global atom indices defining each dihedral angle. Each row contains four indices [i, j, k, l]. A 1-D array of length 4 is accepted and automatically reshaped to (1, 4).

  • shifts (quantity or array-like) –

    Angular increments to apply as a PyUnitWizard angle quantity. Broadcast rules:

    • A scalar float is accepted only when both n_quartets and n_structures are 1.

    • A 1-D array of length n_quartets is reshaped to (n_structures, n_quartets).

    • A 2-D array of shape (n_structures, n_quartets) is used directly.

  • blocks (list of sets or None, default None) – Pre-computed covalent blocks passed through to set_dihedral_angles. When None the blocks are computed on-the-fly.

  • structure_indices ('all' or array-like, default 'all') – Frame indices over which the operation is performed.

  • pbc (bool, default True) – Apply minimum-image convention when the system has a periodic box.

  • in_place (bool, default False) – If True the molecular system is modified in-place and None is returned. If False a new copy is returned with the updated coordinates.

  • engine ({'MolSysMT'}, default 'MolSysMT') – Backend used for the dihedral rotation kernels.

  • skip_digestion (bool, default False) – Whether to skip argument digestion (for internal use on trusted hot paths).

Returns:

A new molecular system with the shifted dihedral angles when in_place=False; None when in_place=True.

Return type:

molecular system or None

Raises:

  • ArgumentError – If dihedral_quartets is not an array-like object, does not have 4 elements in a 1-D case, or does not have shape (n, 4) in the 2-D case.

  • ArgumentLengthError – If a scalar shifts value is provided but there is more than one frame or quartet.

  • .. versionadded: – 1.0.0: