mbe_contrib#

mbgdml.mbe.mbe_contrib(E, Deriv, entity_ids, r_prov_ids, r_prov_specs, E_lower, Deriv_lower, entity_ids_lower, r_prov_ids_lower, r_prov_specs_lower, operation='remove', use_ray=False, ray_address='auto', n_workers=1)[source]#

Adds or removes energy and derivative (i.e., gradients or forces) contributions from a reference.

We use the term “lower” to refer to the lower-order (i.e., smaller) systems. These are the energy and derivative contributions to remove or add to a reference.

Making \(n\)-body predictions (i.e., operation = "add") will often not have r_prov_ids or r_prov_specs as all lower contributions are derived exclusively from these structures. Use None for both of these and this function will assume that all _lower properties apply.

Parameters:

  • E (numpy.ndarray, ndim: 1) – Energies to add or remove contributions from (i.e., reference).

  • Deriv (numpy.ndarray, ndim: 3) – Potential energy surface derivatives (i.e., gradients or forces depending on the sign) of reference structures.

  • entity_ids (numpy.ndarray, ndim: 1) – A uniquely identifying integer specifying what atoms belong to which entities for reference structures. Entities can be a related set of atoms, molecules, or functional group. For example, a water and methanol molecule could be [0, 0, 0, 1, 1, 1, 1, 1, 1].

  • r_prov_ids (dict {int: str} or None) – Species an ID (int) to uniquely identifying labels for each structure if it originated from another source. Labels should always be md5_structures. For example, {0: '6038e101da7fc0085978741832ebc7ad', 1: 'eeaf93dec698de3ecb55e9292bd9dfcb'}.

  • r_prov_specs (numpy.ndarray, ndim: 2 or None) – Structure provenance IDs. This specifies the r_prov_id, structure index from the r_prov_id source, and entity_ids making up the structure.

  • E_lower (numpy.ndarray, ndim: 1) – Lower-order energies.

  • Deriv_lower (numpy.ndarray, ndim: 3) – Potential energy surface derivatives (i.e., gradients or forces depending on the sign) of lower-order structures.

  • entity_ids_lower (numpy.ndarray, ndim: 1) – A uniquely identifying integer specifying what atoms belong to which entities for lower-order structures. Entities can be a related set of atoms, molecules, or functional group. For example, a water and methanol molecule could be [0, 0, 0, 1, 1, 1, 1, 1, 1].

  • r_prov_ids_lower (dict {int: str}) – Species an ID (int) to uniquely identifying labels for each lower-order structure if it originated from another source. Labels should always be md5_structures. For example, {0: '6038e101da7fc0085978741832ebc7ad', 1: 'eeaf93dec698de3ecb55e9292bd9dfcb'}.

  • r_prov_specs_lower (numpy.ndarray, ndim: 2) – Structure provenance IDs. This specifies the r_prov_id, structure index from the r_prov_id source, and entity_ids making up lower-order structures.

  • operation (str, default: 'remove') – 'add' or 'remove' the contributions.

  • use_ray (bool, default: False) – Use ray to parallelize computations.

  • n_workers (int, default: 1) – Total number of workers available for ray. This is ignored if use_ray is False.

  • ray_address (str, default: "auto") – Ray cluster address to connect to.

Returns:

  • numpy.ndarray – Energies with lower-order contributions added or removed.

  • numpy.ndarray – Derivatives with lower-order contributions added or removed.