> ## Documentation Index
> Fetch the complete documentation index at: https://bagel.softnanolab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PAEEnergy

> Energy that drives down the uncertainty in the predicted distances between two groups of residues. This uncertainty is measured by calculating the average normalised predicted alignment error of all the relevant residue pairs.

## Definition

The PAE energy is the mean predicted alignment error between two residue groups, normalized by a maximum PAE value.

$$
E_{\mathrm{PAE}} = \frac{1}{N_{\mathrm{pairs}}} \sum_{\alpha \in G_1, \beta \in G_2} \frac{\mathrm{PAE}_{\alpha\beta}}{\mathrm{PAE}_{\max}}
$$

* $\mathrm{PAE}_{\alpha\beta}$ is the predicted alignment error between residues $\alpha$ and $\beta$
* $\mathrm{PAE}_{\max}$ is 30 Angstrom (the approximate maximum PAE value)
* $G_1$ and $G_2$ are the two residue groups
* $N_{\mathrm{pairs}}$ is the number of residue pairs considered

## Parameters

<ResponseField name="oracle" type="FoldingOracle" required>
  The oracle to use for the energy term.
</ResponseField>

<ResponseField name="residues" type="list[list[Residue]]" required>
  Which residues to include in the first and second group.
</ResponseField>

<ResponseField name="inheritable" type="bool" default="True">
  If a new residue is added next to a residue included in this energy term, this dictates whether that new residue could then be added to this energy term.
</ResponseField>

<ResponseField name="cross_term_only" type="bool" default="True">
  Whether to only consider the uncertainty in distance between group 1 and group 2 atoms. If set to False, also considers the uncertainty in distances between atoms within the same group.
</ResponseField>

<ResponseField name="weight" type="float" default="1.0">
  The weight of the energy term.
</ResponseField>

<ResponseField name="name" type="str | None" default="None">
  Optional name to append to the energy term name.
</ResponseField>

## Methods

### compute

**Parameters**

<ResponseField name="oracles_result" type="OraclesResultDict" required />

## Example

```python theme={null}
import bagel as bg

# Create the folding oracle
esmfold = bg.oracles.ESMFold()

# Define two groups of residues (e.g. hotspot and binder)
hotspot_residues = [residues_target[i] for i in range(10, 20)]
binder_residues = residues_binder

# Minimize PAE between the two groups to drive confident binding
pae_energy = bg.energies.PAEEnergy(
    oracle=esmfold,
    residues=[hotspot_residues, binder_residues],
    weight=5.0,
)

# Add to a state
state = bg.State(
    chains=[binder_chain, target_chain],
    energy_terms=[pae_energy],
    name="my_state",
)
```