valence

Convert SMIRNOFF valence parameters into tensors.

Modules:

• smee –

  Differentiably evaluate energies of molecules using SMIRNOFF force fields

Functions:

• strip_constrained_bonds –

  Remove bonded interactions between distance-constrained atoms.

• strip_constrained_angles –

  Remove angle interactions between angles where all three atoms are constrained

• convert_valence_handlers –

  Convert a list of SMIRNOFF valence handlers into a tensor potential and

strip_constrained_bonds

strip_constrained_bonds(
    parameter_maps: list[ValenceParameterMap],
    constraints: list[set[tuple[int, int]]],
)

Remove bonded interactions between distance-constrained atoms.

Parameters:

• parameter_maps (list[ValenceParameterMap]) –

  The parameter maps to strip.

• constraints (list[set[tuple[int, int]]]) –

  The distanced constrained bonds to exclude for each parameter map.

Source code in smee/converters/openff/valence.py

def strip_constrained_bonds(
    parameter_maps: list[smee.ValenceParameterMap],
    constraints: list[set[tuple[int, int]]],
):
    """Remove bonded interactions between distance-constrained atoms.

    Args:
        parameter_maps: The parameter maps to strip.
        constraints: The distanced constrained bonds to exclude for each parameter map.
    """

    for parameter_map, bonds_to_exclude in zip(
        parameter_maps, constraints, strict=True
    ):
        bonds_to_exclude = {tuple(sorted(idxs)) for idxs in bonds_to_exclude}

        bond_idxs = [
            tuple(sorted(idxs)) for idxs in parameter_map.particle_idxs.tolist()
        ]
        include = [idxs not in bonds_to_exclude for idxs in bond_idxs]

        parameter_map.particle_idxs = parameter_map.particle_idxs[include]
        parameter_map.assignment_matrix = parameter_map.assignment_matrix.to_dense()[
            include, :
        ].to_sparse()

strip_constrained_angles

strip_constrained_angles(
    parameter_maps: list[ValenceParameterMap],
    constraints: list[set[tuple[int, int]]],
)

Remove angle interactions between angles where all three atoms are constrained with distance constraints.

Parameters:

• parameter_maps (list[ValenceParameterMap]) –

  The parameter maps to strip.

• constraints (list[set[tuple[int, int]]]) –

  The distanced constrained bonds to exclude for each parameter map.

Source code in smee/converters/openff/valence.py

def strip_constrained_angles(
    parameter_maps: list[smee.ValenceParameterMap],
    constraints: list[set[tuple[int, int]]],
):
    """Remove angle interactions between angles where all three atoms are constrained
    with distance constraints.

    Args:
        parameter_maps: The parameter maps to strip.
        constraints: The distanced constrained bonds to exclude for each parameter map.
    """

    def is_constrained(idxs_, excluded):
        bonds = {
            tuple(sorted([idxs_[0], idxs_[1]])),
            tuple(sorted([idxs_[0], idxs_[2]])),
            tuple(sorted([idxs_[1], idxs_[2]])),
        }
        return len(bonds & excluded) == 3

    for parameter_map, bonds_to_exclude in zip(
        parameter_maps, constraints, strict=True
    ):
        bonds_to_exclude = {tuple(sorted(idxs)) for idxs in bonds_to_exclude}

        angle_idxs = parameter_map.particle_idxs.tolist()
        include = [not is_constrained(idxs, bonds_to_exclude) for idxs in angle_idxs]

        parameter_map.particle_idxs = parameter_map.particle_idxs[include]
        parameter_map.assignment_matrix = parameter_map.assignment_matrix.to_dense()[
            include, :
        ].to_sparse()

convert_valence_handlers

convert_valence_handlers(
    handlers: list[SMIRNOFFCollection],
    handler_type: str,
    parameter_cols: tuple[str, ...],
) -> tuple[TensorPotential, list[ValenceParameterMap]]

Convert a list of SMIRNOFF valence handlers into a tensor potential and associated parameter maps.

Notes

This function assumes that all parameters come from the same force field

Parameters:

• handlers (list[SMIRNOFFCollection]) –

  The list of SMIRNOFF valence handlers to convert.

• handler_type (str) –

  The type of valence handler being converted.

• parameter_cols (tuple[str, ...]) –

  The ordering of the parameter array columns.

Returns:

• tuple[TensorPotential, list[ValenceParameterMap]] –

  The potential containing tensors of the parameter values, and a list of parameter maps which map the parameters to the interactions they apply to.

Source code in smee/converters/openff/valence.py

def convert_valence_handlers(
    handlers: list[openff.interchange.smirnoff.SMIRNOFFCollection],
    handler_type: str,
    parameter_cols: tuple[str, ...],
) -> tuple[smee.TensorPotential, list[smee.ValenceParameterMap]]:
    """Convert a list of SMIRNOFF valence handlers into a tensor potential and
    associated parameter maps.

    Notes:
        This function assumes that all parameters come from the same force field

    Args:
        handlers: The list of SMIRNOFF valence handlers to convert.
        handler_type: The type of valence handler being converted.
        parameter_cols: The ordering of the parameter array columns.

    Returns:
        The potential containing tensors of the parameter values, and a list of
        parameter maps which map the parameters to the interactions they apply to.
    """
    potential = smee.converters.openff._openff._handlers_to_potential(
        handlers, handler_type, parameter_cols, None
    )

    parameter_key_to_idx = {
        parameter_key: i for i, parameter_key in enumerate(potential.parameter_keys)
    }
    parameter_maps = []

    for handler in handlers:
        particle_idxs = [topology_key.atom_indices for topology_key in handler.key_map]

        assignment_matrix = torch.zeros(
            (len(particle_idxs), len(potential.parameters)), dtype=torch.float64
        )

        for i, parameter_key in enumerate(handler.key_map.values()):
            assignment_matrix[i, parameter_key_to_idx[parameter_key]] += 1.0

        parameter_map = smee.ValenceParameterMap(
            torch.tensor(particle_idxs), assignment_matrix.to_sparse()
        )
        parameter_maps.append(parameter_map)

    return potential, parameter_maps