> ## 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.

# ChemicalPotentialEnergy

> An energy term that purely depends on the number of residues present in a system. Note for statistical mechanics: for some choice of parameters, adding this term is equivalent to making a simulation in the grand-canonical ensemble.

## Definition

The chemical potential energy penalizes deviations from a target number of residues.

$$
E_{\mathrm{chem}} = \mu \left| N_{\mathrm{total}} - N_{\mathrm{target}} \right|^{p}
$$

* $\mu$ is the chemical potential
* $N_{\mathrm{total}}$ is the current total number of residues across all chains
* $N_{\mathrm{target}}$ is the target residue count
* $p$ is the exponent (default 1)

## Parameters

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

<ResponseField name="power" type="float" default="1.0">
  The power to raise the number of residues to.
</ResponseField>

<ResponseField name="target_size" type="int" default="0">
  The target size of the system.
</ResponseField>

<ResponseField name="chemical_potential" type="float" default="1.0">
  The chemical potential of the system.
</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 any oracle (ChemicalPotentialEnergy only depends on residue count)
esmfold = bg.oracles.ESMFold()

# Penalize deviations from a target chain length of 50 residues
chem_potential = bg.energies.ChemicalPotentialEnergy(
    oracle=esmfold,
    target_size=50,
    chemical_potential=1.0,
    weight=1.0,
)

# Add to a state (typically combined with GrandCanonical mutation)
state = bg.State(
    chains=[chain],
    energy_terms=[chem_potential],
    name="my_state",
)
```