Metadata-Version: 2.4
Name: azulene-studio
Version: 0.5.17
Summary: A CLI and Python library to interact with Azulene Studio
Author-email: Azulene Labs <contact@azulenelabs.com>
Project-URL: Homepage, https://www.azulenelabs.com/
Project-URL: Repository, https://github.com/Azulene-Labs/opal-cli
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: supabase<3.0,>=2.4
Requires-Dist: rich<15.0,>=13.7
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

<a name="quickstart"></a>
## Azulene Studio Quick Start Guide: 

- [Azulene Studio Quick Start Guide](#quickstart)
- [Azulene Studio](#Azulene-Opal)
- [Chaining a macrocycle run into Protein-Ligand Interaction Energy / Protein-Ligand Pose Refinement](#macrocycle-chaining)
- [Azulene Studio Job Types](#job-types)


This guide walks you through a **complete working example** of using Azulene Studio to submit and monitor an `Absolute Binding Free Energy (ABFE)` job using a protein and ligand file.

You will learn how to:

a. Install `azulene-studio` from PyPI  
b. Log in  
c. Place your protein + ligand files in the correct location  
d. Submit an `absolute_binding` job (including automatic file upload)  
e. Check job status and retrieve results  

---

## Create and activate a virtual environment (optional)

### For conda
```bash
conda create -n azulene-env python=3.11 -y
conda activate azulene-env
```

### For Python
```bash
# Create a virtual environment
python -m venv azulene-env

# Activate the environment on Windows
azulene-env\Scripts\activate

# Activate the environment on macOS / Linux
source azulene-env/bin/activate
```

---

## a. Install `azulene-studio` from PyPI

```bash
pip install azulene-studio
```

Confirm installation:

```bash
python -m azulene.main --help
```

### CLI commands: `azulene` / `azu`

Installing the package adds two equivalent console commands — **`azulene`** and its
short alias **`azu`** — so every example below can be run as `azulene <command>` or
`azu <command>` (e.g. `azulene login` / `azu login`), or as `python -m azulene.main <command>`.

> **Deprecation:** the old `opal` command (and `import opal`) still work but are
> deprecated aliases from the pre–Azulene Studio naming, and will be removed in a
> future release. Prefer `azulene` / `azu` (and `import azulene`).

### Choosing a backend (`azulene config env`)

Everything talks to **production** unless you say otherwise, and most people
never need to change that. If you are testing against the development backend:

```bash
azulene config env            # which one am I on, and what else is there
azulene config env devel      # use development from now on
azulene config env --reset    # back to production
```

Each environment is a separate account with its own jobs and credits, so each
needs its own `azulene login`; sessions are kept apart, and switching back does
not ask you to log in again. `azulene whoami` always prints which one you are on.

For a single command, or in a script, `AZULENE_ENV=devel azulene ...` does the
same without saving anything. To reach a project neither name covers — a branch
deployment, a local stack — set `AZULENE_SUPABASE_URL` **and**
`AZULENE_SUPABASE_ANON_KEY` together; setting only one is an error rather than a
silent fallback to the production value for the other. In Python these are read
when `azulene` is imported, so export them before `import azulene`, not after.

---

## b. Log in

Run:

```bash
python -m azulene.main login
```

The CLI will securely prompt you:

```
Your email: example@gmail.com
Your password: **********
```

After this, Azulene Studio stores your auth tokens locally so you don’t need to log in again.

---

## c. Example protein and ligand files

Azulene Studio ships with bundled example files you can use right away:

```python
from azulene.examples import T4_LYSOZYME_BENZENE_PDB, BENZENE_BOUND_SDF, TOLUENE_SDF
```

The CLI will automatically detect these as **local files**, upload them to Azulene Studio, and replace the paths with storage URLs.

---

## d. Submit an `absolute_binding` job

The job type is:

```
absolute_binding
```

The required parameters are:

```json
{
  "pdb_file": "",
  "ligand_file": "",
  "ligand_smiles": ""
}
```

### **Example 1: Using the bundled sample files**

```python
from azulene import jobs
from azulene.examples import T4_LYSOZYME_BENZENE_PDB, BENZENE_BOUND_SDF

result = jobs.submit(
    job_type="absolute_binding",
    input_data={
        "pdb_file": str(T4_LYSOZYME_BENZENE_PDB),
        "ligand_file": str(BENZENE_BOUND_SDF),
        "ligand_smiles": "c1ccccc1"
    }
)

print(result)
```

You should see something like:

```
📤 Uploading local files...
✅ Job submitted successfully
{
  "job_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "submitted",
  "message": "Job submitted successfully"
}
```

### **Example 2: Absolute Binding Free Energy (ABFE) (Ligand Already in PDB)**

This example runs an absolute_binding job using:
- A protein PDB file
- A ligand inside the PDB file
- A SMILES string for the ligand
- Shortened equilibration & production lengths
- Only 1 protocol repeat

```python
from azulene import auth, jobs
from azulene.examples import FKB_MODEL_PDB

# 1. Log in (Only if you haven't logged in)
auth.login(email="your@email.com", password="yourpassword")

# 2. Submit the job
input_data = {
    "pdb_file": str(FKB_MODEL_PDB),
    "ligand_smiles": "CS(=O)C",
    "protocol_repeats": 1,
    "ligand_in_pdb_file": True,
    "complex_prod_length": 0.1,
    "solvent_prod_length": 0.1,
    "complex_equil_length": 0.02,
    "solvent_equil_length": 0.02
}

result = jobs.submit(
    job_type="absolute_binding",
    input_data=input_data
)

print(result)
```

---

## e. Submit an `Absolute Hydration Free Energy` job

The job type is:

```text
aqueous_solvation
````

The required parameters are:

```json
{
  "smiles": ""
}
```

### **Example: Using a simple SMILES (`CCO`)**


```python
from azulene import jobs

result = jobs.submit(
    job_type="aqueous_solvation",
    input_data={
        "smiles": "CCO"
    }
)

print(result)
```

You should see something like:

```text
✅ Job submitted successfully
{
  "job_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "submitted",
  "message": "Job submitted successfully"
}
```


## f. Other useful commands

### **1. List your jobs**

Last 5 jobs (default):

```bash
python -m azulene.main jobs get-jobs
```

All jobs:

```bash
python -m azulene.main jobs get-jobs --all
```

Filter by job type and status:

```bash
python -m azulene.main jobs get-jobs \
  --job-type absolute_binding \
  --status completed
```

Filter by date:

```bash
python -m azulene.main jobs get-jobs \
  --start-date 2025-12-01T00:00:00Z \
  --end-date   2025-12-05T00:00:00Z
```

---

### **2. Check a specific job**

```bash
python -m azulene.main jobs get --job-id YOUR_JOB_ID
```

This returns:

* job status
* input data
* results (if completed)
* timestamps
* any error messages

---

### **3. Poll running jobs**

```bash
python -m azulene.main jobs check-running-jobs
```

Use this to check on running jobs.

---

### **4. Cancel a job**

```bash
python -m azulene.main jobs cancel --job-id YOUR_JOB_ID
```

Only works if the job is still running.

---

<a name="Azulene-Opal"></a>
# Azulene Studio


This guide shows how to:

1. Log in
2. Submit a job
3. Inspect and filter jobs
4. Get / cancel a specific job
5. Poll running jobs
6. Check service health & job types
7. Submit a batch of jobs

---

## How to download Azulene Studio

```shellscript
pip install azulene-studio
```

## 0. Imports (Python)

```python
from azulene import auth, jobs
```

---

## 1. Log in


```python
from azulene import auth

res = auth.login(email="test@example.com", password="pass123")
print(res)  # {"ok": True, "message": "Logged in successfully!"}
```

You stay logged in via locally stored tokens until you explicitly log out.

---

## 2. Check who you are


```python
from azulene import auth

res = auth.whoami()
print(res)
# {
#   "ok": True,
#   "user": { ... full user object ... },
#   "slim": {
#       "email": "...",
#       "role": "...",
#       "approved": True,
#       ...
#   }
# }
```

---

## 3. Submit a single job

Example job type: `generate_conformers` with a SMILES and number of conformers.

```python
from azulene import jobs

res = jobs.submit(
    job_type="generate_conformers",
    input_data={"smiles": "CCO", "num_conformers": 5},  # dict
)
print(res)
# {"ok": True, "data": {"job_id": "...", "status": "submitted", ...}}
```

(You *can* also pass a JSON string instead of a dict if you want.)

---

## 4. List and filter jobs

By default, the server returns **the last 5 jobs** for the current user.
You can ask for all jobs, limit, or filter by job_type, status, or date range.


```python
from azulene import jobs

# Last 5 jobs (default)
print(jobs.get_jobs())

# All jobs
print(jobs.get_jobs(all_jobs=True))

# Last 10 jobs
print(jobs.get_jobs(limit=10))

# Filter by job_type and status
print(
    jobs.get_jobs(
        job_type="generate_conformers",
        status="completed",
    )
)

# Filter by created_at date range (ISO timestamps)
print(
    jobs.get_jobs(
        start_date="2025-12-01T00:00:00Z",
        end_date="2025-12-05T00:00:00Z",
    )
)
```

Each call returns something like:

```python
{"ok": True, "data": [ { "id": "...", "job_type": "...", ... }, ... ]}
```

---

## 5. Get a specific job

Once you have a `job_id`, you can fetch that job’s details.


```python
from azulene import jobs

res = jobs.get(job_id="YOUR_JOB_ID")
print(res)
# {"ok": True, "data": { "id": "...", "status": "...", "input_data": {...}, "results": {...}, ... }}
```

---

## 6. Cancel a job

If a job is still running, you can cancel it.


```python
from azulene import jobs

res = jobs.cancel(job_id="YOUR_JOB_ID")
print(res)
# {"ok": True, "data": {...}}
```

---

## 7. Poll running jobs

This endpoint checks any currently running jobs and update their statuses.


```python
from azulene import jobs

res = jobs.check_running_jobs()
print(res)
# {"ok": True, "data": {...}}  # depends on your backend payload
```

---

## 8. Health check

Check that the Azulene Studio backend is reachable.


```python
from azulene import jobs

res = jobs.check_health()
print(res)
# {"ok": True, "data": {...}}  on success
```


---

## 9. Discover available job types

List job types supported by the current backend.


```python
from azulene import jobs

res = jobs.get_job_types()
print(res)
# {"ok": True, "data": {"job_types": [{"id": "generate_conformers", "name": "3D Molecular Conformer Generation", ...}, ...]}}
```


---

## 10. Submit a batch of jobs (same job_type, many inputs)

You can submit **multiple jobs at once** for a single `job_type`.
Each entry in the list becomes a **separate job** under the hood.


```python
from azulene import jobs

small_input_list = [
    {"smiles": "CCO",   "num_conformers": 5},
    {"smiles": "CCCO",  "num_conformers": 3},
    {"smiles": "CCcndO","num_conformers": 2},
]

res = jobs.submit_batch_jobs(
    job_type="generate_conformers",
    input_data=small_input_list,
)
print(res)
# {
#   "ok": True,
#   "results": [
#       {
#         "index": 0,
#         "input": {...},
#         "response": {
#             "ok": True,
#             "data": {
#                 "job_id": "...",
#                 "status": "submitted",
#                 "message": "Job submitted successfully",
#                 ...
#             }
#         }
#       },
#       ...
#   ]
# }
```

---

## 11. Log out

When you’re done, you can clear the local tokens.


```python
from azulene import auth

res = auth.logout()
print(res)  # {"ok": True}
```

---

## TL;DR minimal workflows

```python
from azulene import auth, jobs

# 1) Log in
auth.login(email="test@example.com", password="pass123")

# 2) Submit a job
submit_res = jobs.submit(
    job_type="generate_conformers",
    input_data={"smiles": "CCO", "num_conformers": 5},
)
print(submit_res)

# 3) List recent jobs
print(jobs.get_jobs())

# 4) Fetch that job by ID
job_id = submit_res["data"]["job_id"]
print(jobs.get(job_id=job_id))
```


### Help Commands

```bash
python -m azulene.main --help

python -m azulene.main jobs --help

python -m azulene.main jobs submit --help
```


<a name="macrocycle-chaining"></a>
## Chaining a macrocycle run into Protein-Ligand Interaction Energy / Protein-Ligand Pose Refinement

`boltz_macrocycle` folds the complex twice.

The **peptide fold** is the tool's primary output and is unchanged: it produces
`affinity_pkd`, the crosslink report, the `top_k_*` interface scores and the
`pose_*.pdb` files shown in the viewer.

The **ligand fold** co-folds the same system a second time with the binder
declared as a molecule from its own SMILES, affinity head off. It exists only
for what happens after prediction: **Protein-Ligand Interaction Energy** (`opal_ml_score`) and
**Protein-Ligand Pose Refinement** (`opal_ml_optimize`) take a ligand, so without it the binder's
chemistry has to be re-perceived from diffusion coordinates — which on a stapled
peptide returned an amide as a hemiaminal and a hydrocarbon staple as a
bicyclobutane. Set the `ligand_arm` input to `false` to skip it: the result goes
back to a single fold and the run takes roughly half as long.

### The one thing to get right when you chain

Submit the `opal_ml_inputs` block the result publishes, and read
`opal_ml_inputs.from_arm` to know which fold it describes.

* `from_arm: "ligand"` — the ligand fold ran, and this block is **its** complex,
  chains and `ligand_smiles`. Those coordinates are not the `pose_*.pdb` files,
  and `affinity_pkd` does not refer to them. `arm_note` says the same thing in
  the payload.
* `from_arm: "peptide"` — the ligand fold was turned off, or could not resolve
  the binder to a molecule. The block is the two-chain peptide hand-off as
  before, and a `warnings` entry says which of the two it was.

Either way the block is submittable as it stands. Do not rebuild it from
`pose_*.pdb`.

Both folds' hand-offs are reachable. `opal_ml_inputs` is the recommended one;
`opal_ml_inputs_by_arm` is `{"peptide": {...}, "ligand": {...}}`, carrying
whichever arms produced a usable hand-off. Reach for it when you specifically
want to score the peptide complex `affinity_pkd` describes rather than the
recommended one — which is the one case where the recommended block is not what
you want.

```python
from azulene import jobs

results = jobs.get(job_id=macrocycle_job_id)["data"]["results"]
handoff = results["opal_ml_inputs"]

print(handoff["from_arm"])        # "ligand" or "peptide"
print(handoff["usage"])           # the routing this job wants, in words

payload = {
    "protein_file": handoff["complex_file"]["download_url"],
    "chain_id": handoff["receptor_chain"],
    "binder_chain": handoff["binder_chain"],
}
if handoff.get("ligand_smiles"):
    payload["ligand_smiles"] = handoff["ligand_smiles"]

jobs.submit("opal_ml_score", payload)
```

### Naming the binder's chemistry

The ligand fold needs a SMILES for the binder. Three ways to get one, in the
order the job tries them:

| Input           | `ligand_smiles_source` | When to use it |
| --------------- | ---------------------- | -------------- |
| `ligand_smiles` | `supplied`             | You want a specific molecule or protonation state. Used verbatim — it is not re-charged at pH 7.4. |
| `helm`          | `helm`                 | You already describe the binder in HELM2. Read for CHEMISTRY only, never as a starting conformer. The reader here knows far fewer monomers than the one `peptide_structure` uses, so a valid HELM naming an ncAA may not parse; it then falls through to the CCD assembly with a warning and `ligand_smiles_source` comes back `ccd`, so the fold still runs and the envelope records that the HELM was not the source. |
| neither         | `ccd`                  | The default. Assembled from `binder.sequence`, `modifications` and `bonds` using the same PDB Chemical Component Dictionary entries the peptide fold uses. |

### Result keys the ligand fold adds

Present only when the ligand fold ran.

| Key                           | Type    | Meaning |
| ----------------------------- | ------- | ------- |
| `ligand_smiles`               | string  | The molecule that was folded. |
| `ligand_smiles_source`        | string  | `ccd`, `helm` or `supplied` — whether the chemistry was derived or asserted. |
| `ligand_n_heavy_atoms`        | integer | Heavy-atom count of that molecule. |
| `ligand_net_charge`           | integer | Formal net charge of that molecule. |
| `arm_interface_agreement`     | number  | Jaccard overlap of the receptor residues each fold's top pose contacts. The one cross-arm number that means something: it needs no atom correspondence between a polymer and a ligand, and it answers whether representing the binder differently moved it to a different site. |
| `arm_binder_centroid_shift_a` | number  | Distance in Ångström between the two folds' top-pose binder centroids. |
| `opal_ml_inputs_by_arm`       | object  | `{"peptide": …, "ligand": …}` — both folds' hand-offs, for when you want the one `opal_ml_inputs` did not recommend. Only arms that produced a usable hand-off appear. |
| `ligand_arm`                  | object  | The ligand fold's own block — `smiles`, `smiles_source`, `n_heavy_atoms`, `net_charge`, `largest_ring`, `n_samples`, `n_poses_returned`, `n_binder_tokens` and its own `top_k_labels` / `top_k_ipsae` / `top_k_iptm` / `top_k_pdockq2` / `top_k_mean_plddt` / `top_k_cluster_size`. |

The ligand fold's `top_k_ipsae` and `top_k_pdockq2` are nested inside
`ligand_arm` rather than placed beside the peptide fold's, because they are not
on the same scale: a polymer is one token per residue and a ligand one per atom,
so the same binder is 14 tokens in one fold and 119 in the other. Rank the
ligand fold's poses against each other with them; do not compare them across
folds. `arm_interface_agreement` is the number that does compare.

## Opal PPI naming compatibility

Use `opal_ppi` for **Rank protein-protein interfaces using Opal**. Existing
`boltz_ppi` submissions and example selectors continue to address the same
function; permissions, credits, inputs, scores, and pose ordering are unchanged.
Other Boltz tools keep their names.

This SDK requests `X-Opal-Public-Names: 1` when calling the API. PPI catalog and
result responses then use `opal_ppi`, public example URLs, and Opal download
filenames. Internal worker paths are omitted. If an existing result reader
requires the legacy response fields, set `AZULENE_LEGACY_TOOL_NAMES=1` before
calling the SDK. API clients that omit the header retain the legacy response
format. Previously generated archives retain their original contents.

Release dependency: publish the three `v1/opal/opal_ppi/` example aliases and
deploy the backend alias and response support before releasing these CLI/SDK
changes. The catalog snapshot in this branch records source changes; it is
not proof that a production deployment is ready.

<a name="job-types"></a>
<!-- BEGIN GENERATED job-types — tools/regen_job_types_docs.py -->
<!-- Generated by tools/regen_job_types_docs.py from the live get-func-defs catalog on 2026-09-01 (33 job types). Do not edit by hand. -->

## Azulene Studio Job Types

Every tool below is generated from the live Azulene Studio catalog — the same
definitions the web wizard and `azulene jobs get-job-types` read. Do not
hand-edit this section; run `python tools/regen_job_types_docs.py` instead.
The same content is kept standalone in
[Job_Types.md](https://github.com/Azulene-Labs/opal-cli/blob/main/Job_Types.md).

Field names are **not** shared between tools. For the same protein,
`absolute_binding` takes `pdb_file` and `docking` takes `structure_file`.
Copy each tool's own table.

This is the full submittable surface: fields that the Studio wizard or
`azulene jobs get-job-types` hide as operational detail (`platform`, derived
values) are documented here too.

You can fetch the same catalog live:

```bash
azulene jobs get-job-types              # id / name table
azulene jobs get-job-types --markdown   # this reference, regenerated
```

---

### Overview

| ID                             | Name                                                   | Category                        | Description |
| ------------------------------ | ------------------------------------------------------ | ------------------------------- | ----------- |
| `protac_pose_prediction`       | PROTAC Ternary Complex Pose Prediction                 | Structure Predictions           | Predict ternary PROTAC linker poses (target + E3 ligase) via rigid-body prescan, GPU… |
| `generate_conformers`          | 3D Molecular Conformer Generation                      | Structure Generation / Sampling | Generate molecular conformers from SMILES notation |
| `aqueous_solvation`            | Absolute Hydration Free Energy                         | Molecular Property Prediction   | Calculates the absolute solvation free energy of a molecule (SMILES) or peptide (HELM) in… |
| `predict_protein_properties`   | Protein and Peptide Developability Prediction          | Property Prediction             | Predict key developability properties of a protein or peptide directly from its sequence… |
| `relative_fe`                  | Relative Hydration Free Energy                         | Molecular Property Prediction   | Calculates the relative free energy between two similar molecules in water using alchemical… |
| `relative_fe_uaa`              | Relative Hydration Free Energy for ncAAs               | Molecular Property Prediction   | Calculates the relative free energy between two (unnatural) amino acid structures in water… |
| `solvent_transfer_free_energy` | Solvent Transfer Free Energy                           | Molecular Property Prediction   | Calculates the transfer free energy of a molecule (SMILES) or peptide (HELM) between two… |
| `nonaqueous_solvation`         | Absolute Solvation Free Energy (Non-Aqueous)           | Molecular Property Prediction   | Calculates the absolute solvation free energy of a molecule (SMILES) or peptide (HELM) in a… |
| `reaction_free_energy`         | Aqueous Reaction Free Energy                           | Molecular Property Prediction   | Calculates the reaction free energy in aqueous solution. |
| `deprotonation_fe`             | Deprotonation Free Energy (pKa)                        | Molecular Property Prediction   | Calculates the deprotonation free energy in aqueous solution (pKa proxy). Accepts SMILES or… |
| `absolute_binding`             | Absolute Binding Free Energy (ABFE)                    | Binding Free Energy             | Calculates the absolute binding free energy of a ligand to a protein in aqueous solution. |
| `relative_binding`             | Relative Binding Free Energy (RBFE)                    | Binding Free Energy             | Calculates the relative binding free energy between two ligands to a protein in aqueous… |
| `lipid_permeation`             | Lipid Bilayer Permeation Free Energy                   | Molecular Property Prediction   | Calculates the free energy of a molecule (SMILES) or peptide (HELM) permeating through a lipid… |
| `lipid_permeation_rfe`         | Relative Lipid Bilayer Permeation Free Energy          | Molecular Property Prediction   | Calculates the relative free energy of permeation through a lipid bilayer between two… |
| `covalent_docking`             | Covalent Docking                                       | Docking & Pose                  | Predict and refine 3D binding poses of a covalent inhibitor at a specified protein residue… |
| `docking`                      | Docking                                                | Docking & Pose                  | Physics-based docking of a ligand into a binding site you supply — there is no pocket finding… |
| `sequential_docking`           | Cofactor & Ligand Docking                              | Docking & Pose                  | Docks ligands, fragments or cofactors one at a time, each stage taking the previous result as… |
| `opal_ml_optimize`             | Protein-Ligand Pose Refinement                         | Structure-Based Drug Design     | Relaxes a pose you supply; it does not generate one. L-BFGS minimisation of the ligand or… |
| `opal_ml_score`                | Protein-Ligand Interaction Energy                      | Structure-Based Drug Design     | Single-point protein–ligand interaction energy from the OPAL-ML neural network potential, in… |
| `peptide_structure`            | Peptide 3D Structure Generation (HELM)                 | Structure Generation / Sampling | Generate 3D structures from HELM notation for linear and cyclic peptides, including… |
| `protein_mutation_ddg_fold`    | Protein Mutation Folding Stability (Physics-based ΔΔG) | Free Energy Methods             | Predict the change in folding free energy on amino-acid mutation (natural AAs + 14 ncAAs: Aib… |
| `boltz_prediction`             | Boltz-2 Structure + Affinity Prediction                | Structure Predictions           | Co-fold up to 12 protein chains with up to 8 cofactors and 1 ligand using Boltz-2. The minimal… |
| `opal_ppi`                     | Rank protein-protein interfaces using Opal             | Co-folding                      | Predict and rank candidate protein-protein interfaces from two protein sequences. Returns… |
| `boltz_macrocycle`             | Macrocycle and Cyclic Peptide Binding Prediction       | Structure Predictions           | Folds a macrocyclic or stapled peptide against a receptor and scores the interface; the binder… |
| `chai_prediction`              | Chai-1 Complex Structure Prediction                    | Structure Predictions           | All-atom co-folding with Chai-1 (Apache-2.0). Supports protein, RNA, DNA, and small-molecule… |
| `openfold3_prediction`         | OpenFold3 Complex Structure Prediction                 | Structure Predictions           | AF3-parity all-atom structure prediction with OpenFold3 (Apache-2.0). Within experimental… |
| `openfold2_prediction`         | OpenFold2 Protein Structure Prediction                 | Structure Predictions           | Single-chain and multimer protein structure prediction with OpenFold2 (Apache-2.0). OpenFold2… |
| `mpnn_design`                  | ProteinMPNN Sequence Design (Inverse Folding)          | Structure Predictions           | Design new amino-acid sequences that fold to a backbone structure you provide (inverse… |
| `mpnn_stability`               | ThermoMPNN Mutation Stability (ML-based ΔΔG)           | Structure Predictions           | Predict how mutations change a protein's folding stability (ΔΔG, in kcal/mol) from its… |
| `esm2_embed`                   | ESM-2 Protein Sequence Embeddings                      | Protein Embeddings              | Turn protein sequences into ESM-2 embeddings — numeric vectors that capture each protein's… |
| `esm2_mutation_score`          | ESM-2 Zero-Shot Mutation Scoring                       | Protein Mutation Scoring        | Score how point mutations affect a protein, with no training data needed. ESM-2 rates each… |
| `esmfold_predict`              | ESMFold Single-Chain Structure Prediction              | Structure Predictions           | Single-chain structure prediction from sequence with ESMFold — no MSA, up to 1024 residues… |
| `crystal_prediction`           | Organic Crystal Structure Prediction (CSP)             | Structure Generation / Sampling | Predict organic crystal structures from a SMILES string or an uploaded molecular geometry… |

---

### 1. PROTAC Ternary Complex Pose Prediction (`protac_pose_prediction`)

**Description:** Predict ternary PROTAC linker poses (target + E3 ligase) via rigid-body prescan, GPU minimization, and cross-PDB GBM scoring. Optional experimental ground-truth comparison reports topological PROTAC and PROTAC+pocket RMSD.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/protac_pose_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default  | Description |
| --------------------------- | ------- | -------- | -------- | ----------- |
| `job_id`                    | string  | no       | —        | Set by the platform. Names the per-job working directory on the shared volume; a value you supply is replaced, because two jobs under one name would share one directory. |
| `target_pdb_content`        | file    | yes      | —        | Target protein + warhead — upload a PDB file. |
| `e3_pdb_content`            | file    | yes      | —        | E3 ligase + recruiter — upload a PDB file. |
| `linker_smiles`             | string  | yes      | —        | Linker as a SMILES fragment carrying two attachment points: [*:1] is the bond to the warhead, [*:2] the bond to the E3 recruiter. The two are not interchangeable. Docs: https://docs.azulenelabs.com/tools/protac_pose_prediction/ |
| `warhead_attach_atom_idx`   | integer | yes      | —        | Warhead atom the linker bonds to. 0-based over the HEAVY atoms of the warhead_chain ligand, in the order they appear in the uploaded target PDB — not an index into any SMILES. Viewers number atoms from 1, so subtract 1. Docs: https://docs.azulenelabs.com/tools/protac_pose_prediction/. Minimum 0. |
| `recruiter_attach_atom_idx` | integer | yes      | —        | E3-recruiter atom the linker bonds to. 0-based over the HEAVY atoms of the recruiter_chain ligand, in the order they appear in the uploaded E3 PDB — not an index into any SMILES. Viewers number atoms from 1, so subtract 1. Docs: https://docs.azulenelabs.com/tools/protac_pose_prediction/. Minimum 0. |
| `target_chain`              | string  | no       | `A`      | Target protein chain id(s); single 'A' or comma-separated 'B,C,D'. |
| `e3_chain_label`            | string  | no       | `B`      | E3 protein chain id(s); single or comma-separated. |
| `warhead_chain`             | string  | no       | `X`      | Chain ID of the warhead ligand within the target PDB (the small molecule bound to the target protein). Single chain id. |
| `recruiter_chain`           | string  | no       | `Y`      | Chain ID of the E3-recruiter ligand within the E3 PDB (the small molecule bound to the E3 ligase). Single chain id. |
| `preset`                    | string  | no       | `medium` | Angular search preset (dropdown). 'quick' = coarse 20-deg grid (~0.36x compute, fast/low-accuracy demo); 'medium' = 15-deg grid (production reference the GBM ranker was trained on); 'long' = 10-deg grid, theta_max=110 deg to recover high-theta experimental poses (slowest). One of `quick`, `medium`, `long`. |
| `n_prescan_chunks`          | integer | no       | `8`      | Parallel prescan distance-bin chunks. Range 1–16. |
| `warhead_smiles`            | string  | no       | —        | Warhead SMILES template (may contain an attachment point; correct bond orders). |
| `e3_anchor_smiles`          | string  | no       | —        | E3-anchor SMILES template (may contain an attachment point; correct bond orders). |
| `gt_complex_pdb_content`    | file    | no       | —        | Optional experimental ground-truth ternary complex — upload a PDB file for RMSD comparison. |
| `gt_ligand_resname`         | string  | no       | —        | Ground-truth PROTAC ligand residue name (required if gt_complex_pdb_content given). |
| `gt_target_chain`           | string  | no       | `A`      | Ground-truth target chain id. |
| `gt_e3_chain`               | string  | no       | `B`      | Ground-truth E3 chain id(s). |
| `keep_dirs`                 | boolean | no       | `true`   | Persist full pose / overlay / summary outputs as a downloadable ZIP (retrievable via `opal jobs download`). Disable for the scalar JSON summary only. |

#### Example Input

```json
{
  "target_pdb_content": "<local path or storage key>",
  "e3_pdb_content": "<local path or storage key>",
  "linker_smiles": "[*:1]CCOCCOCC[*:2]",
  "warhead_attach_atom_idx": 15,
  "recruiter_attach_atom_idx": 17,
  "target_chain": "A",
  "e3_chain_label": "B,C,D",
  "preset": "quick"
}
```

`target_pdb_content`, `e3_pdb_content` take a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit protac_pose_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID              | Name                        | Description |
| ----------------------- | --------------------------- | ----------- |
| `7jtp-wdr5-vhl-quick`   | WDR5-VHL (7JTP) - quick     | Predict how the degrader MS67 bridges WDR5 to the VHL ligase (RCSB 7JTP). WDR5 scaffolds the… |
| `6sis-brd4-vhl-quick`   | BRD4-VHL (6SIS) - quick     | Predict how macroPROTAC-1 bridges the BET bromodomain BRD4 to VHL (RCSB 6SIS). Its linker is… |
| `7jtp-wdr5-vhl`         | WDR5-VHL (7JTP) - medium    | Predict how the degrader MS67 bridges WDR5 to VHL, at the 15-deg grid the pose ranker was… |
| `6sis-brd4-vhl`         | BRD4-VHL (6SIS) - medium    | Predict how the macrocyclic degrader macroPROTAC-1 bridges BRD4 to VHL, at the reference… |
| `8g1q-smarca2-vhl`      | SMARCA2-VHL (8G1Q) - medium | Predict how the degrader cmpd_3603 bridges SMARCA2 to VHL (RCSB 8G1Q). SMARCA2 (BRM) is… |
| `8g1q-smarca2-vhl-long` | SMARCA2-VHL (8G1Q) - long   | The same SMARCA2-VHL degrader on the widest search (10-deg grid, theta_max 110 deg). In 8G1Q… |

---

### 2. 3D Molecular Conformer Generation (`generate_conformers`)

**Description:** Generate molecular conformers from SMILES notation

**Category:** Structure Generation / Sampling · **Docs:** <https://docs.azulenelabs.com/tools/generate_conformers/> · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field            | Type    | Required | Default | Description |
| ---------------- | ------- | -------- | ------- | ----------- |
| `smiles`         | string  | yes      | —       | SMILES notation of the molecule |
| `num_conformers` | integer | yes      | `5`     | Number of conformers to generate. Range 1–100. |

#### Example Input

```json
{
  "smiles": "CCO",
  "num_conformers": 5
}
```

#### Featured Examples

Run one with `azulene examples submit generate_conformers <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID             | Name                 | Description |
| ---------------------- | -------------------- | ----------- |
| `aspirin-conformers`   | Aspirin conformers   | Generate five 3D conformers of aspirin (acetylsalicylic acid) from its SMILES using RDKit ETKDG. |
| `ibuprofen-conformers` | Ibuprofen conformers | Generate five 3D conformers of ibuprofen from its SMILES using RDKit ETKDG. |
| `caffeine-conformers`  | Caffeine conformers  | Generate five 3D conformers of caffeine, a small rigid heteroaromatic molecule. |

---

### 3. Absolute Hydration Free Energy (`aqueous_solvation`)

**Description:** Calculates the absolute solvation free energy of a molecule (SMILES) or peptide (HELM) in water using alchemical transformations. Provide exactly one of 'smiles' or 'helm'.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/aqueous_solvation/> · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `smiles`                    | string  | no       | —       | SMILES string of the molecule. Provide this OR 'helm'. |
| `helm`                      | string  | no       | —       | Peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Single-letter residues, dot-separated; non-canonical residues in brackets (e.g. [Aib], [dF]). Provide this or 'smiles'. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `conformer_method`          | string  | no       | `etkdg` | 3D conformer generator for HELM input: 'etkdg' (fast, default) or 'xtb' (GFN2-xTB, slower, better geometries). Ignored when SMILES input is used. One of `etkdg`, `xtb`. |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct ligand protonation state at the specified pH. Disable if your inputs are already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `solvent_equil_length`      | number  | no       | `0.08`  | Solvent equilibration length in nanoseconds per replica. Minimum 0. |
| `solvent_prod_length`       | number  | no       | `0.4`   | Solvent production length in nanoseconds per replica. Minimum 0. |
| `vacuum_equil_length`       | number  | no       | `0.08`  | Vacuum equilibration length in nanoseconds per replica. Minimum 0. |
| `vacuum_prod_length`        | number  | no       | `0.4`   | Vacuum production length in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles": "CCO"
}
```

#### Featured Examples

Run one with `azulene examples submit aqueous_solvation <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                   | Name                             | Description |
| ---------------------------- | -------------------------------- | ----------- |
| `ethanol`                    | Hydration free energy of ethanol | Absolute hydration free energy of ethanol by alchemical decoupling in explicit water (short… |
| `methanol-aqueous-solvation` | Methanol hydration               | Hydration free energy of methanol, a classic small FreeSolv reference molecule. |
| `toluene-aqueous-solvation`  | Toluene hydration                | Hydration free energy of toluene, a hydrophobic aromatic FreeSolv reference. |
| `methane-aqueous-solvation`  | Methane hydration free energy    | Hydration free energy of methane — the canonical apolar-solvation benchmark, and the simplest… |

---

### 4. Protein and Peptide Developability Prediction (`predict_protein_properties`)

**Description:** Predict key developability properties of a protein or peptide directly from its sequence: solubility, aggregation, subcellular localization, intrinsic disorder, toxicity, melting temperature (Tm), and MHC binding (class I and II). Use it to triage or rank candidate sequences before committing to wet-lab work. Provide exactly one of a plain amino-acid sequence or a HELM string.

**Category:** Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/predict_protein_properties/> · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field                | Type    | Required | Default | Description |
| -------------------- | ------- | -------- | ------- | ----------- |
| `sequence`           | string  | no       | —       | The protein or peptide sequence to score, using the 20 standard amino acids (e.g. MKTAYIAKQRQ...). Provide this or HELM, not both. Sequences longer than 1022 residues are truncated, and anything over 2044 residues is rejected. |
| `helm`               | string  | no       | —       | Peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Converted to a plain sequence for this tool: bracketed non-canonical residues are REMOVED from the sequence, not substituted - [Aib] and [dF] are deleted, so the peptide scored is one residue SHORTER for each. Cyclization is ignored, and only the first PEPTIDE block is read. Provide this or the sequence field. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `properties`         | array   | no       | `[]`    | Pick which properties to predict. Leave empty to run the full panel (all of them). Items are any of `solubility`, `aggregation`, `disorder`, `localization`, `toxicity`, `tm`, `mhc`. |
| `properties_options` | object  | no       | `{}`    | Optional per-property settings. Only MHC binding and localization take any; the other five properties have no options and none are shown for them. For example, {"mhc": {"peptide_length": 15, "mhc_class": "II"}} runs MHC binding for class II at the given peptide length. Leave empty to use sensible defaults. |
| `return_per_residue` | boolean | no       | `false` | Also return per-residue scores where available (currently disorder and aggregation hotspots), so you can see which regions drive each prediction. Off by default; large results are delivered as a downloadable attachment. |
| `return_embedding`   | boolean | no       | `false` | Also return the protein's sequence embedding (a numeric fingerprint), handy for downstream similarity search or clustering. Off by default. |
| `model_variant`      | string  | no       | `650M`  | Model size to run. 650M (default) is fast and accurate for most uses; 3B is a larger model for slightly higher accuracy at higher cost. One of `650M`, `3B`. |

#### Example Input

```json
{
  "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAYLAKHIGCNHIGFRLT",
  "properties": [
    "solubility",
    "disorder",
    "tm"
  ]
}
```

#### Featured Examples

Run one with `azulene examples submit predict_protein_properties <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                           | Name                                     | Description |
| ------------------------------------ | ---------------------------------------- | ----------- |
| `protein-properties-alpha-synuclein` | α-synuclein (intrinsic disorder)         | Disorder / aggregation / solubility heads on alpha-synuclein, the canonical intrinsically… |
| `protein-properties-melittin`        | Melittin (toxicity / solubility)         | Toxicity / solubility / localization heads on melittin, the textbook membrane-lysing… |
| `protein-properties-ova-peptide`     | OVA323-339 epitope (MHC-II + solubility) | MHC class-II (via properties_options) plus solubility heads on the OVA323-339 model epitope. |
| `ubiquitin`                          | Ubiquitin property profile               | Sequence-based ML property profile (solubility, aggregation, disorder, Tm) for human… |
| `amyloid-beta-42`                    | Amyloid-beta(1-42) profile               | Property profile for amyloid-beta(1-42), the aggregation-prone Alzheimer's peptide -… |

---

### 5. Relative Hydration Free Energy (`relative_fe`)

**Description:** Calculates the relative free energy between two similar molecules in water using alchemical transformations.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/relative_fe/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `smiles_a`                  | string  | yes      | —       | SMILES string representation of the first molecule |
| `smiles_b`                  | string  | yes      | —       | SMILES string representation of the second molecule |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct ligand protonation state at the specified pH. Disable if your inputs are already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `equil_length`              | number  | no       | `0.08`  | Equilibration length in nanoseconds per replica. Minimum 0. |
| `prod_length`               | number  | no       | `0.4`   | Production length in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles_a": "CCO",
  "smiles_b": "CCC"
}
```

#### Featured Examples

Run one with `azulene examples submit relative_fe <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID               | Name                            | Description |
| ------------------------ | ------------------------------- | ----------- |
| `ethanol-to-propane`     | Relative FE: ethanol to propane | Relative solvation free energy between ethanol and propane via a single-topology alchemical… |
| `benzene-to-toluene-fe`  | Benzene to toluene              | Relative hydration free energy for adding a methyl to benzene. |
| `phenol-to-catechol-fe`  | Phenol to catechol              | Relative hydration free energy for adding a hydroxyl to phenol. |
| `methanol-to-ethanol-fe` | Methanol to ethanol relative FE | Relative solvation free energy for methanol to ethanol — a single methyl-group alchemical… |

---

### 6. Relative Hydration Free Energy for ncAAs (`relative_fe_uaa`)

**Description:** Calculates the relative free energy between two (unnatural) amino acid structures in water using alchemical transformations.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/relative_fe_uaa/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `sequence_a`                | string  | yes      | —       | Peptide sequence. Uppercase one-letter codes for natural AAs (e.g. 'GAG'). For UAAs: use library names in angle brackets (pF-Phe, oF-Phe, mF-Phe, Sar, N-Me-Ala), SMILES in angle brackets (e.g. '&lt;NC(C)(C)C(=O)O&gt;'), or lowercase placeholders with uaa_map (e.g. 'GxG' + uaa_map {'x':'pF-Phe'}) |
| `sequence_b`                | string  | yes      | —       | Second peptide sequence (same format as first) |
| `uaa_map`                   | string  | no       | —       | Maps a lowercase placeholder in the sequence to an unnatural amino acid, by library name or SMILES. Placeholders are one lowercase letter plus optional digits (e.g. x, a2). |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct ligand protonation state at the specified pH. Disable if your inputs are already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `equil_length`              | number  | no       | `0.08`  | Equilibration length in nanoseconds per replica. Minimum 0. |
| `prod_length`               | number  | no       | `0.4`   | Production length in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "sequence_a": "YGH",
  "sequence_b": "<pF-Phe>GH"
}
```

#### Featured Examples

Run one with `azulene examples submit relative_fe_uaa <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID        | Name                            | Description |
| ----------------- | ------------------------------- | ----------- |
| `ygh-pf-phe-scan` | ncAA scan: Tyr to pF-Phe in YGH | Relative free energy of substituting tyrosine with the non-canonical amino acid… |

---

### 7. Solvent Transfer Free Energy (`solvent_transfer_free_energy`)

**Description:** Calculates the transfer free energy of a molecule (SMILES) or peptide (HELM) between two solvents using alchemical transformations. Provide exactly one of 'smiles_solute' or 'helm'.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/solvent_transfer_free_energy/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `smiles_solute`             | string  | no       | —       | SMILES string of the solute. Provide this OR 'helm'. |
| `helm`                      | string  | no       | —       | Peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Single-letter residues, dot-separated; non-canonical residues in brackets (e.g. [Aib], [dF]). Provide this or the SMILES field. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `conformer_method`          | string  | no       | `etkdg` | 3D conformer generator for HELM input: 'etkdg' (fast, default) or 'xtb' (GFN2-xTB, slower). Ignored when SMILES input is used. One of `etkdg`, `xtb`. |
| `smiles_solvent_a`          | string  | yes      | —       | SMILES string representation of the first solvent. Use `None' for vacuum. |
| `smiles_solvent_b`          | string  | yes      | —       | SMILES string representation of the second solvent. Use `None' for vacuum. |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct solute protonation state at the specified pH. Disable if your input is already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `solvent_equil_length`      | number  | no       | `0.08`  | Equilibration length in nanoseconds for actual-solvent leg(s). Minimum 0. |
| `solvent_prod_length`       | number  | no       | `0.4`   | Production length in nanoseconds for actual-solvent leg(s). Minimum 0. |
| `vacuum_equil_length`       | number  | no       | `0.08`  | Equilibration length in nanoseconds for the vacuum leg (when smiles_solvent_a or _b is 'None'). Minimum 0. |
| `vacuum_prod_length`        | number  | no       | `0.4`   | Production length in nanoseconds for the vacuum leg. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of independent replicas. Reported uncertainty combines per-replica uncertainty with the replica-to-replica spread. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `false` | Preserve scratch / output directories for download. Disable to save storage. |

#### Example Input

```json
{
  "smiles_solute": "CCO",
  "smiles_solvent_a": "None",
  "smiles_solvent_b": "O"
}
```

#### Featured Examples

Run one with `azulene examples submit solvent_transfer_free_energy <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                     | Name                                | Description |
| ------------------------------ | ----------------------------------- | ----------- |
| `ethanol-water-to-methanol`    | Ethanol transfer: water to methanol | Transfer free energy of ethanol from water to methanol, from the difference of absolute… |
| `benzene-water-to-cyclohexane` | Benzene water to cyclohexane        | Transfer free energy of benzene between water and cyclohexane. |
| `toluene-water-to-octanol`     | Toluene water to octanol            | Transfer free energy of toluene between water and octanol (logP-type). |

---

### 8. Absolute Solvation Free Energy (Non-Aqueous) (`nonaqueous_solvation`)

**Description:** Calculates the absolute solvation free energy of a molecule (SMILES) or peptide (HELM) in a non-aqueous solvent using alchemical transformations. Provide exactly one of 'smiles_solute' or 'helm'.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/nonaqueous_solvation/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `smiles_solute`             | string  | no       | —       | SMILES string of the solute. Provide this OR 'helm'. |
| `helm`                      | string  | no       | —       | Peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Single-letter residues, dot-separated; non-canonical residues in brackets (e.g. [Aib], [dF]). Provide this or the SMILES field. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `conformer_method`          | string  | no       | `etkdg` | 3D conformer generator for HELM input: 'etkdg' (fast, default) or 'xtb' (GFN2-xTB, slower). Ignored when SMILES input is used. One of `etkdg`, `xtb`. |
| `smiles_solvent`            | string  | yes      | —       | SMILES string of the organic solvent (e.g. `CCO` ethanol, `CO` methanol, `CCCCCC` hexane, `CS(=O)C` DMSO) |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct solute protonation state at the specified pH. Disable if your input is already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `solvent_equil_length`      | number  | no       | `0.08`  | Solvent equilibration length in nanoseconds per replica. Minimum 0. |
| `solvent_prod_length`       | number  | no       | `0.4`   | Solvent production length in nanoseconds per replica. Minimum 0. |
| `vacuum_equil_length`       | number  | no       | `0.08`  | Vacuum equilibration length in nanoseconds per replica. Minimum 0. |
| `vacuum_prod_length`        | number  | no       | `0.4`   | Vacuum production length in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of independent replicas. Reported uncertainty combines per-replica uncertainty with the replica-to-replica spread. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `false` | Preserve scratch / output directories for download. Disable to save storage. |

#### Example Input

```json
{
  "smiles_solute": "CCO",
  "smiles_solvent": "CO"
}
```

#### Featured Examples

Run one with `azulene examples submit nonaqueous_solvation <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID            | Name                             | Description |
| --------------------- | -------------------------------- | ----------- |
| `ethanol-in-methanol` | Solvation of ethanol in methanol | Absolute solvation free energy of ethanol in methanol by alchemical decoupling (short demo… |

---

### 9. Aqueous Reaction Free Energy (`reaction_free_energy`)

**Description:** Calculates the reaction free energy in aqueous solution.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/reaction_free_energy/> · **Submission modes:** `single`

#### Input Schema

| Field                    | Type    | Required | Default | Description |
| ------------------------ | ------- | -------- | ------- | ----------- |
| `smiles_reactant`        | string  | yes      | —       | SMILES string representations of the reactants, separated by commas |
| `smiles_product`         | string  | yes      | —       | SMILES string representations of the products, separated by commas |
| `stoichiometry_reactant` | string  | yes      | —       | Stoichiometry of the reactants, separated by commas |
| `stoichiometry_product`  | string  | yes      | —       | Stoichiometry of the products, separated by commas |
| `solvent_equil_length`   | number  | no       | `0.08`  | Solvent equilibration length in nanoseconds per replica. Minimum 0. |
| `solvent_prod_length`    | number  | no       | `0.4`   | Solvent production length in nanoseconds per replica. Minimum 0. |
| `vacuum_equil_length`    | number  | no       | `0.08`  | Vacuum equilibration length in nanoseconds per replica. Minimum 0. |
| `vacuum_prod_length`     | number  | no       | `0.4`   | Vacuum production length in nanoseconds per replica. Minimum 0. |
| `platform`               | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`       | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `use_xtb`                | boolean | no       | `false` | Use xTB for gas phase calculations |
| `keep_dirs`              | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles_reactant": "CC=O",
  "smiles_product": "C=CO",
  "stoichiometry_reactant": "1",
  "stoichiometry_product": "1",
  "use_xtb": true
}
```

#### Featured Examples

Run one with `azulene examples submit reaction_free_energy <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                | Name                                    | Description |
| ------------------------- | --------------------------------------- | ----------- |
| `keto-enol-acetaldehyde`  | Acetaldehyde keto-enol tautomerization  | Reaction free energy of the acetaldehyde keto-enol tautomerization (CH3CHO -&gt; CH2=CHOH) in… |
| `keto-enol-acetone`       | Acetone keto-enol                       | Aqueous keto-enol tautomerization free energy of acetone. |
| `cis-trans-2-butene`      | 2-butene cis to trans                   | Aqueous cis to trans isomerization free energy of 2-butene. |
| `co2-hydration`           | CO2 hydration to carbonic acid          | Reaction free energy for the hydration of carbon dioxide to carbonic acid (CO2 + H2O -&gt… |
| `cyclohexanone-keto-enol` | Cyclohexanone keto-enol tautomerisation | Keto-enol tautomerisation free energy for cyclohexanone to cyclohex-1-en-1-ol in aqueous… |

---

### 10. Deprotonation Free Energy (pKa) (`deprotonation_fe`)

**Description:** Calculates the deprotonation free energy in aqueous solution (pKa proxy). Accepts SMILES or HELM for each side -- provide exactly one of (smiles_prot, helm_protonated) and exactly one of (smiles_deprot, helm_deprotonated).

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/deprotonation_fe/> · **Submission modes:** `single`

#### Input Schema

| Field                  | Type    | Required | Default | Description |
| ---------------------- | ------- | -------- | ------- | ----------- |
| `smiles_prot`          | string  | no       | —       | SMILES of the protonated species. Provide this OR 'helm_protonated'. |
| `helm_protonated`      | string  | no       | —       | HELM2 notation for the protonated peptide (HA), e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `helm_deprotonated`    | string  | no       | —       | HELM2 notation for the deprotonated peptide (A-), e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `conformer_method`     | string  | no       | `etkdg` | 3D conformer generator for HELM inputs: 'etkdg' (fast, default) or 'xtb' (GFN2-xTB). One of `etkdg`, `xtb`. |
| `smiles_deprot`        | string  | no       | —       | SMILES of the deprotonated species. Provide this OR 'helm_deprotonated'. |
| `solvent_equil_length` | number  | no       | `0.08`  | Solvent equilibration length in nanoseconds per replica. Minimum 0. |
| `solvent_prod_length`  | number  | no       | `0.4`   | Solvent production length in nanoseconds per replica. Minimum 0. |
| `vacuum_equil_length`  | number  | no       | `0.08`  | Vacuum equilibration length in nanoseconds per replica. Minimum 0. |
| `vacuum_prod_length`   | number  | no       | `0.4`   | Vacuum production length in nanoseconds per replica. Minimum 0. |
| `platform`             | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`     | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `use_xtb`              | boolean | no       | `false` | Use xTB for gas phase calculations |
| `keep_dirs`            | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles_prot": "C(=O)O",
  "smiles_deprot": "C(=O)[O-]",
  "use_xtb": true
}
```

#### Featured Examples

Run one with `azulene examples submit deprotonation_fe <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                  | Name                                         | Description |
| --------------------------- | -------------------------------------------- | ----------- |
| `formic-acid`               | Deprotonation FE of formic acid              | Deprotonation (pKa-related) free energy of formic acid to formate in water with xTB reference… |
| `acetic-acid-deprotonation` | Acetic acid pKa                              | Deprotonation free energy of acetic acid (experimental pKa about 4.76). |
| `phenol-deprotonation`      | Phenol pKa                                   | Deprotonation free energy of phenol (experimental pKa about 10). |
| `imidazole-deprotonation`   | Imidazole deprotonation (histidine analogue) | Deprotonation free energy of imidazole to imidazolate (neutral N-H to anion). Imidazole is the… |

---

### 11. Absolute Binding Free Energy (ABFE) (`absolute_binding`)

**Description:** Calculates the absolute binding free energy of a ligand to a protein in aqueous solution.

**Category:** Binding Free Energy · **Docs:** <https://docs.azulenelabs.com/tools/absolute_binding/> · **Submission modes:** `single`, `workflow_node`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `pdb_file`                  | file    | yes      | —       | PDB file of the protein. May optionally contain the ligand |
| `ligand_file`               | file    | no       | —       | File of the ligand (SDF, PDB, or CIF format) |
| `ligand_in_pdb_file`        | boolean | no       | `false` | Specifies whether the ligand is contained within the provided protein PDB file |
| `ligand_chain_id`           | string  | no       | —       | Chain ID of the ligand, used only when the ligand is read from a PDB or CIF — ignored for an SDF ligand. Detected only when that structure IS the protein file ('ligand_in_pdb_file' on) and ends .pdb: largest non-water HETATM residue wins. Anywhere else chain B is assumed with nothing logged, so set it. Docs: https://docs.azulenelabs.com/tools/absolute_binding/ |
| `ligand_residue_name`       | string  | no       | —       | Residue name of the ligand (the 3-letter code on its HETATM records), used only when the ligand is read from a PDB or CIF — ignored for an SDF ligand. Detected under the same one condition as ligand_chain_id, and where that is not met, LIG is assumed. Docs: https://docs.azulenelabs.com/tools/absolute_binding/ |
| `ligand_smiles`             | string  | yes      | —       | SMILES string representation of the ligand |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct ligand protonation state at the specified pH. Disable if your inputs are already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `solvent_equil_length`      | number  | no       | `0.02`  | Solvent equilibration length of the ligand in nanoseconds per replica. Minimum 0. |
| `solvent_prod_length`       | number  | no       | `0.1`   | Solvent production length of the ligand in nanoseconds per replica. Minimum 0. |
| `complex_equil_length`      | number  | no       | `0.02`  | Complex equilibration length of the ligand-protein complex in nanoseconds per replica. Minimum 0. |
| `complex_prod_length`       | number  | no       | `0.1`   | Complex production length of the ligand-protein complex in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "pdb_file": "<local path or storage key>",
  "ligand_file": "<local path or storage key>",
  "ligand_smiles": "CCO"
}
```

`pdb_file`, `ligand_file` take a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit absolute_binding <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID         | Name                                | Description |
| ------------------ | ----------------------------------- | ----------- |
| `hif2a-belzutifan` | HIF-2α + belzutifan-class inhibitor | ABFE with a PT-2385-class HIF-2α inhibitor. HIF-2α inhibition is the mechanism of FDA-approved… |
| `cdk2-lig-1h1q`    | CDK2 inhibitor (ABFE)               | Absolute binding free energy of a neutral aminopyrimidine inhibitor to CDK2, from the OpenFE… |
| `pfkfb3-lig-24`    | PFKFB3 inhibitor (ABFE)             | Absolute binding free energy of a neutral inhibitor to PFKFB3, from the OpenFE benchmark. |

---

### 12. Relative Binding Free Energy (RBFE) (`relative_binding`)

**Description:** Calculates the relative binding free energy between two ligands to a protein in aqueous solution.

**Category:** Binding Free Energy · **Docs:** <https://docs.azulenelabs.com/tools/relative_binding/> · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default | Description |
| --------------------------- | ------- | -------- | ------- | ----------- |
| `pdb_file`                  | file    | yes      | —       | Upload a PDB file or fetch from RCSB by ID |
| `ligand_file_a`             | file    | no       | —       | File of the first ligand (SDF, PDB, or CIF format) |
| `ligand_file_b`             | file    | no       | —       | File of the second ligand (SDF, PDB, or CIF format) |
| `ligand_in_pdb_file_a`      | boolean | no       | `false` | Specifies whether the first ligand is contained within the provided protein PDB file |
| `ligand_in_pdb_file_b`      | boolean | no       | `false` | Specifies whether the second ligand is contained within the provided protein PDB file |
| `ligand_residue_name_a`     | string  | no       | `LIG`   | Residue name of the first ligand in the PDB file |
| `ligand_residue_name_b`     | string  | no       | `LIG`   | Residue name of the second ligand in the PDB file |
| `smiles_a`                  | string  | yes      | —       | SMILES string representation of the first ligand |
| `smiles_b`                  | string  | yes      | —       | SMILES string representation of the second ligand |
| `assign_protonation_states` | boolean | no       | `true`  | Automatically assigns the correct ligand protonation state at the specified pH. Disable if your inputs are already protonated. |
| `ph`                        | number  | no       | `7`     | pH value for protonation state |
| `equil_length`              | number  | no       | `0.08`  | Equilibration length in nanoseconds per replica. Minimum 0. |
| `prod_length`               | number  | no       | `0.4`   | Production length in nanoseconds per replica. Minimum 0. |
| `platform`                  | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`          | integer | no       | `3`     | Number of protocol repeats for uncertainty estimation. Minimum 1. |
| `keep_dirs`                 | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "pdb_file": "<local path or storage key>",
  "ligand_file_a": "<local path or storage key>",
  "ligand_file_b": "<local path or storage key>",
  "smiles_a": "CCO",
  "smiles_b": "CCC"
}
```

`pdb_file`, `ligand_file_a`, `ligand_file_b` take a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit relative_binding <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID             | Name                                  | Description |
| ---------------------- | ------------------------------------- | ----------- |
| `tyk2-ejm-31-ejm-50`   | TYK2 ejm_31 → ejm_50 (RBFE benchmark) | RBFE between two TYK2 inhibitors from the OpenFreeEnergy benchmark (doi… |
| `cdk2-lig-21-lig-22`   | CDK2 pair (RBFE)                      | Relative binding free energy between two neutral CDK2 inhibitors from the OpenFE benchmark. |
| `pfkfb3-lig-24-lig-33` | PFKFB3 pair (RBFE)                    | Relative binding free energy between two neutral PFKFB3 inhibitors from the OpenFE benchmark. |

---

### 13. Lipid Bilayer Permeation Free Energy (`lipid_permeation`)

**Description:** Calculates the free energy of a molecule (SMILES) or peptide (HELM) permeating through a lipid bilayer using umbrella sampling. Provide exactly one of 'smiles' or 'helm'.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/lipid_permeation/> · **Submission modes:** `single`

#### Input Schema

| Field              | Type    | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | ----------- |
| `smiles`           | string  | no       | —       | SMILES string of the solute. Provide this OR 'helm'. |
| `helm`             | string  | no       | —       | Peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Single-letter residues, dot-separated; non-canonical residues in brackets (e.g. [Aib], [dF]). Provide this or the SMILES field. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `conformer_method` | string  | no       | `etkdg` | 3D conformer generator for HELM input: 'etkdg' (fast, default) or 'xtb' (GFN2-xTB, slower). One of `etkdg`, `xtb`. |
| `lipid_type`       | string  | yes      | —       | Lipid bilayer to permeate. Runs at 298.15 K. Fluid at that temperature: DOPC, DLPC (dilauroyl 12:0, not dilinoleoyl), POPC. Near their transition: DMPC (Tm 24 C), POPE (25 C). BELOW their transition and therefore gel-phase, so not comparable to literature fluid-phase permeabilities: DLPE (29 C), DPPC (41 C). One of `DPPC`, `DMPC`, `DOPC`, `DLPE`, `DLPC`, `POPE`, `POPC`. |
| `equil_length`     | number  | no       | `0.08`  | Equilibration length in nanoseconds per replica. Minimum 0. |
| `prod_length`      | number  | no       | `0.4`   | Production length in nanoseconds per replica. Minimum 0. |
| `platform`         | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `keep_dirs`        | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles": "O",
  "lipid_type": "POPC"
}
```

#### Featured Examples

Run one with `azulene examples submit lipid_permeation <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID     | Name                           | Description |
| -------------- | ------------------------------ | ----------- |
| `ethanol-popc` | Ethanol permeation across POPC | Membrane permeation free-energy profile of ethanol across a POPC lipid bilayer (short demo… |

---

### 14. Relative Lipid Bilayer Permeation Free Energy (`lipid_permeation_rfe`)

**Description:** Calculates the relative free energy of permeation through a lipid bilayer between two molecules (SMILES) using an alchemical perturbation. Provide both 'smiles_a' and 'smiles_b'.

**Category:** Molecular Property Prediction · **Docs:** <https://docs.azulenelabs.com/tools/lipid_permeation_rfe/> · **Submission modes:** `single`

#### Input Schema

| Field               | Type    | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ----------- |
| `smiles_a`          | string  | yes      | —       | SMILES string of the first molecule. |
| `smiles_b`          | string  | yes      | —       | SMILES string of the second molecule (a small modification of the first works best). |
| `lipid_type`        | string  | yes      | —       | Lipid bilayer to permeate. Runs at 298.15 K. Fluid at that temperature: DOPC, DLPC (dilauroyl 12:0, not dilinoleoyl), POPC. Near their transition: DMPC (Tm 24 C), POPE (25 C). BELOW their transition and therefore gel-phase, so not comparable to literature fluid-phase permeabilities: DLPE (29 C), DPPC (41 C). One of `DPPC`, `DMPC`, `DOPC`, `DLPE`, `DLPC`, `POPE`, `POPC`. |
| `equil_length`      | number  | no       | `0.08`  | Equilibration length in nanoseconds per replica. Minimum 0. |
| `prod_length`       | number  | no       | `0.4`   | Production length in nanoseconds per replica. Minimum 0. |
| `ion_concentration` | number  | no       | `0`     | Salt concentration in molar for the simulation box. Minimum 0. |
| `platform`          | string  | no       | `CUDA`  | OpenMM compute platform for simulations. One of `CUDA`, `OpenCL`, `CPU`, `Reference`. |
| `protocol_repeats`  | integer | no       | `3`     | Number of independent repeats of the alchemical protocol. Minimum 1. |
| `keep_dirs`         | boolean | no       | `true`  | Preserves full simulation outputs for download. Disable only if you don't need the raw data. |

#### Example Input

```json
{
  "smiles_a": "CCO",
  "smiles_b": "CCCO",
  "lipid_type": "POPC"
}
```

#### Featured Examples

Run one with `azulene examples submit lipid_permeation_rfe <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                 | Name                       | Description |
| -------------------------- | -------------------------- | ----------- |
| `ethanol-to-propanol-popc` | Ethanol to propanol (POPC) | Relative permeation free energy across a POPC bilayer for the single-methyl edit from ethanol… |
| `methanol-to-ethanol-popc` | Methanol to ethanol (POPC) | Relative permeation free energy across a POPC bilayer for the smallest alcohol edit, methanol… |
| `benzene-to-toluene-popc`  | Benzene to toluene (POPC)  | Relative permeation free energy across a POPC bilayer for adding a methyl to benzene. |

---

### 15. Covalent Docking (`covalent_docking`)

**Description:** Predict and refine 3D binding poses of a covalent inhibitor at a specified protein residue, then rank the poses with Opal scores. Provide the protein structure, inhibitor SMILES, and the reactive residue's chain, name, number, and atom. Supports warheads including boronic acids, acrylamides, nitriles, and sulfonyl fluorides.

**Category:** Docking & Pose · **Docs:** <https://docs.azulenelabs.com/tools/covalent_docking/> · **Submission modes:** `single`

#### Input Schema

| Field                  | Type    | Required | Default    | Description |
| ---------------------- | ------- | -------- | ---------- | ----------- |
| `structure_file`       | file    | yes      | —          | Protein structure file (PDB or CIF format) |
| `ligand_smiles`        | string  | yes      | —          | SMILES string of the covalent inhibitor (must contain a reactive warhead) |
| `drug_smiles`          | string  | no       | —          | Legacy name for 'ligand_smiles'. Accepted and rewritten onto 'ligand_smiles' on submission, so existing scripts, saved workflows and chained jobs keep working; new callers should use 'ligand_smiles'. |
| `chain_id`             | string  | yes      | —          | Chain identifier in the protein structure (e.g., 'A') |
| `target_resname`       | string  | yes      | —          | Three-letter name of the reactive residue. One of `SER`, `CYS`, `LYS`, `THR`, `HIS`, `TYR`. |
| `target_resid`         | integer | yes      | —          | Sequence number of the reactive residue |
| `target_atom`          | string  | yes      | —          | Reactive atom name (e.g. OG for SER, SG for CYS). REQUIRED: it is not auto-detected, and omitting it makes the whole job run as ordinary non-covalent docking with no error - the same silent downgrade. |
| `covalent_element`     | string  | no       | `B`        | Element of the atom that actually REACTS, not the warhead's most conspicuous heteroatom - a vinyl sulfone reacts at the beta-carbon, so choose C. Note the default here is B (boronic acid); sequential_docking defaults the same field to C. One of `B`, `C`, `S`, `P`. |
| `warhead_smarts`       | string  | no       | —          | Custom SMARTS pattern for warhead detection, with a :1 atom map marking the reactive atom. NOT CURRENTLY IMPLEMENTED — accepted and then ignored; the warhead is detected from built-in patterns and cannot be overridden. Docs: https://docs.azulenelabs.com/tools/covalent_docking/ |
| `protonate`            | boolean | no       | `true`     | Assign physiological protonation state at the target pH. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. The receptor and ligand are always protonated. |
| `ph`                   | number  | no       | `7.4`      | pH for protonation state assignment. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Protonation always runs at pH 7.4. Range 0–14. |
| `placement`            | string  | no       | `combined` | Ligand placement strategy. 'combined' is most thorough. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. One of `combined`, `directed`, `tetrahedral`. |
| `max_steps`            | integer | no       | `700`      | Maximum optimization steps per orientation trial. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 100–2000. |
| `keep_cofactors`       | string  | no       | —          | Comma-separated cofactor residue names to retain, e.g. 'ZN,NDP'; empty strips every non-standard residue. Waters go unless you add HOH. Organic cofactors are scored as NEUTRAL, so an anionic cofactor offsets absolute dG while ranking within one receptor is unaffected. Docs: https://docs.azulenelabs.com/tools/covalent_docking/ |
| `extra_chains`         | string  | no       | —          | Comma-separated additional chain IDs to include (e.g. 'B' or 'B,C'). |
| `optimize_and_score`   | boolean | no       | `false`    | Chain geometry optimization and ML scoring straight after covalent docking. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Docs: https://docs.azulenelabs.com/tools/covalent_docking/ |
| `opt_fmax`             | number  | no       | `0.05`     | Convergence force threshold (eV/Å) for pose refinement. Only used when Optimize + Score is enabled. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 0.005–1. |
| `opt_maxiter`          | integer | no       | `200`      | Maximum optimization iterations per pose. Only used when Optimize + Score is enabled. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 10–2000. |
| `top_k`                | integer | no       | `5`        | Number of top-ranked covalent poses to refine and score. Only used when Optimize + Score is enabled. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 1–20. |
| `n_conformers`         | integer | no       | —          | CLASSICAL arm sample count: how many ligand conformers are enumerated in the pocket. Each is tried in many orientations (~60 trials per conformer), so classical runtime scales roughly linearly with it. LEAVE EMPTY for the automatic default — 8 for a small molecule, 12 when cyclic-peptide/macrocycle sampling is on. A value here overrides the macrocycle default too, so leave it empty unless you mean to. Docs: https://docs.azulenelabs.com/tools/docking/. Range 1–64. |
| `n_generative_samples` | integer | no       | —          | GENERATIVE arm sample count: how many poses OpalFM diffuses. This is GPU time and is the largest cost knob on the job. LEAVE EMPTY for the automatic default — 30 for a small molecule, 48 when cyclic-peptide/macrocycle sampling is on. Set 0 to switch the generative arm OFF and dock with the classical arm alone: much cheaper, and it gives up the arm that finds near-native poses the classical score ranks low. Docs: https://docs.azulenelabs.com/tools/docking/. Range 0–256. |
| `n_poses_per_arm`      | integer | no       | —          | OPAL-ML POOL size: how many poses from EACH arm are geometry-optimized and scored with OPAL-ML. The two arms are ranked separately by their own native metric, so the pool is 2 x this number — 3 is the 6-pose table you see in the results. Raising it searches more of what the arms already generated and costs one OPAL-ML optimization per extra pose, which is the expensive end of the job. LEAVE EMPTY for the automatic default — 3 per arm. Docs: https://docs.azulenelabs.com/tools/covalent_docking/. Range 1–10. |

#### Example Input

```json
{
  "structure_file": "<local path or storage key>",
  "ligand_smiles": "OB(O)c1ccccc1",
  "chain_id": "A",
  "target_resname": "SER",
  "target_resid": 70,
  "target_atom": "OG",
  "covalent_element": "B"
}
```

`structure_file` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit covalent_docking <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID              | Name                                | Description |
| ----------------------- | ----------------------------------- | ----------- |
| `mpro-paxlovid`         | Paxlovid → SARS-CoV-2 Mpro (Cys145) | Covalently docks Paxlovid (nirmatrelvir) into SARS-CoV-2 main protease, forming the C–S… |
| `proteasome-bortezomib` | Bortezomib → 20S proteasome (Thr1)  | Covalently docks the boronic-acid drug bortezomib (Velcade) to the catalytic N-terminal Thr1… |
| `kras-g12c`             | KRAS G12C → Cys12 (chloroacetamide) | Covalently docks a research-class GTP-competitive chloroacetamide inhibitor to the oncogenic… |

---

### 16. Docking (`docking`)

**Description:** Physics-based docking of a ligand into a binding site you supply — there is no pocket finding. Orientations are minimized in the pocket, with a dedicated arm for macrocycles. The center is in Angstroms in the uploaded structure's own frame. Which model scores the pose depends on the ligand: macrocycles and cyclic peptides go to Opal-Dock v3 (`confidence: macrocycle`), everything else to a regressor fitted on covalent complexes (`noncovalent_low_confidence`). Both are ranking scores, not affinities.

**Category:** Docking & Pose · **Docs:** <https://docs.azulenelabs.com/tools/docking/> · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field                   | Type    | Required | Default | Description |
| ----------------------- | ------- | -------- | ------- | ----------- |
| `structure_file`        | file    | yes      | —       | Protein structure file (PDB or CIF format) |
| `ligand_smiles`         | string  | no       | —       | SMILES string of the ligand or cofactor to dock. Provide this OR 'helm'. |
| `drug_smiles`           | string  | no       | —       | Legacy name for 'ligand_smiles'. Accepted and rewritten onto 'ligand_smiles' on submission, so existing scripts, saved workflows and chained jobs keep working; new callers should use 'ligand_smiles'. |
| `helm`                  | string  | no       | —       | Cyclic or linear peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0 — provide this OR 'ligand_smiles'. Declare ring closures in the connection section (head-to-tail 1:R1-N:R2; disulfide or side-chain bridge i:R3-j:R3): a declared macrocycle is docked with the cyclic-peptide sampling arm, and a ring you do not declare cannot be detected. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `ligand_file`           | file    | no       | —       | Ligand as an SDF, MOL, MOL2 or PDB file — provide this OR `ligand_smiles` OR `helm`. Only the molecule is taken from it, not its coordinates: docking builds its own conformers in the pocket. A multi-record SDF docks the first record only. Docs: https://docs.azulenelabs.com/tools/docking/. Accepts `.sdf,.mol,.mol2,.pdb`. |
| `conformer_method`      | string  | no       | `etkdg` | Reserved for HELM input. The docking pipeline builds its own conformer ensemble in the pocket, so this does not currently change the result. One of `etkdg`, `xtb`. |
| `macrocycle_sampling`   | string  | no       | `auto`  | Whether to dock with the macrocycle sampling arm. 'auto', the default, turns it on for a flexible ring larger than 8 atoms, which an ordinary small molecule never triggers; it is markedly slower. 'off' forces the small-molecule settings. Docs: https://docs.azulenelabs.com/tools/docking/. One of `auto`, `on`, `off`. |
| `chain_id`              | string  | yes      | —       | Chain identifier in the protein structure (e.g., 'A') |
| `binding_site_center`   | string  | yes      | —       | Pocket center in Angstroms, in the coordinate frame of the uploaded structure. This is the ONLY input that steers the docking. The wizard can average binding_site_residues into it for you. |
| `binding_site_residues` | string  | no       | —       | Pocket residues as (name, number) pairs, used only to fill in `binding_site_center` — it has NO effect once a center is set, which is required. Numbers are as written in the file, matched across every chain and ignoring insertion codes. Docs: https://docs.azulenelabs.com/tools/docking/ |
| `placement_radius`      | number  | no       | `8`     | Radius (Angstroms) of the random placement sphere around the binding site center. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 3–20. |
| `n_orientations`        | integer | no       | `8`     | Number of random orientations per conformer. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 1–50. |
| `keep_cofactors`        | string  | no       | —       | Comma-separated cofactor residue names to retain, e.g. 'ZN,NDP'; empty strips every non-standard residue. Waters go unless you add HOH. Organic cofactors are scored as NEUTRAL, so an anionic cofactor offsets absolute dG while ranking within one receptor is unaffected. Docs: https://docs.azulenelabs.com/tools/docking/ |
| `fmax`                  | number  | no       | `0.5`   | Force convergence threshold (eV/Ang). NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. |
| `max_steps`             | integer | no       | `700`   | Maximum optimization steps per trial. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 100–2000. |
| `use_electrostatics`    | boolean | no       | `true`  | Enable Coulomb interactions in classical scoring. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Electrostatics are always on; setting this false does not disable them. |
| `protonate`             | boolean | no       | `true`  | Assign ligand protonation state at the target pH. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. The receptor and ligand are always protonated. |
| `ph`                    | number  | no       | `7.4`   | pH for ligand protonation state assignment. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Protonation always runs at pH 7.4. Range 0–14. |
| `n_conformers`          | integer | no       | —       | CLASSICAL arm sample count: how many ligand conformers are enumerated in the pocket. Each is tried in many orientations (~60 trials per conformer), so classical runtime scales roughly linearly with it. LEAVE EMPTY for the automatic default — 8 for a small molecule, 12 when cyclic-peptide/macrocycle sampling is on. A value here overrides the macrocycle default too, so leave it empty unless you mean to. Docs: https://docs.azulenelabs.com/tools/docking/. Range 1–64. |
| `n_generative_samples`  | integer | no       | —       | GENERATIVE arm sample count: how many poses OpalFM diffuses. This is GPU time and is the largest cost knob on the job. LEAVE EMPTY for the automatic default — 30 for a small molecule, 48 when cyclic-peptide/macrocycle sampling is on. Set 0 to switch the generative arm OFF and dock with the classical arm alone: much cheaper, and it gives up the arm that finds near-native poses the classical score ranks low. Docs: https://docs.azulenelabs.com/tools/docking/. Range 0–256. |
| `n_poses_per_arm`       | integer | no       | —       | OPAL-ML POOL size: how many poses from EACH arm are geometry-optimized and scored with OPAL-ML. The two arms are ranked separately by their own native metric, so the pool is 2 x this number — 3 is the 6-pose table you see in the results. Raising it searches more of what the arms already generated and costs one OPAL-ML optimization per extra pose, which is the expensive end of the job. LEAVE EMPTY for the automatic default — 3 per arm. Docs: https://docs.azulenelabs.com/tools/docking/. Range 1–10. |

##### `binding_site_residues` — one entry

| Field     | Type    | Required | Default | Description |
| --------- | ------- | -------- | ------- | ----------- |
| `resname` | string  | yes      | —       | Three-letter residue name, e.g. SER |
| `resid`   | integer | yes      | —       | Residue number as written in the uploaded file |

#### Example Input

```json
{
  "structure_file": "<local path or storage key>",
  "ligand_smiles": "c1ccc(cc1)C(=N)N",
  "chain_id": "A",
  "binding_site_center": "[12.5, 8.3, -4.1]",
  "binding_site_residues": "[[\"BEN\",1]]"
}
```

`structure_file` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit docking <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                            | Name                                                | Description |
| ------------------------------------- | --------------------------------------------------- | ----------- |
| `t4-lysozyme-ethylbenzene`            | Ethylbenzene → T4 lysozyme L99A cavity              | Non-covalent self-docking of ethylbenzene into the engineered hydrophobic cavity of T4… |
| `dhfr-trimethoprim`                   | Trimethoprim → DHFR (keep NADPH)                    | Cofactor-aware non-covalent docking of the antifolate antibiotic trimethoprim into human… |
| `carbonic-anhydrase-sulfanilamide`    | Sulfanilamide → carbonic anhydrase II (keep Zn²⁺)   | Cofactor-aware non-covalent docking of the prototypical sulfonamide inhibitor sulfanilamide… |
| `er-estradiol`                        | 17-beta-estradiol to estrogen receptor alpha        | Non-covalent docking of the endogenous hormone 17-beta-estradiol into the ligand-binding… |
| `streptavidin-cyclic-hexapeptide`     | Cyclic hexapeptide → streptavidin (HELM, disulfide) | Dock a disulfide-cyclized hexapeptide, Ac-CHPQFC-NH2, into streptavidin (PDB 1SLD). The binder… |
| `spsb2-cyclic-rgd`                    | cyclo-RGDINNNV → SPSB2 (HELM, head-to-tail)         | Dock a head-to-tail cyclized octapeptide into the SPRY domain of SPSB2 (PDB 5XN3). Closed by a… |
| `streptavidin-cyclic-hexapeptide-sdf` | Cyclic hexapeptide → streptavidin (SDF ligand file) | The same binder and the same pocket as 'Cyclic hexapeptide → streptavidin', supplied as a 3D… |

---

### 17. Cofactor & Ligand Docking (`sequential_docking`)

**Description:** Docks ligands, fragments or cofactors one at a time, each stage taking the previous result as a frozen receptor; covalent and non-covalent stages may be mixed. Every non-covalent stage needs its own `binding_site_center` or is rejected at submission.

**Category:** Docking & Pose · **Docs:** <https://docs.azulenelabs.com/tools/sequential_docking/> · **Submission modes:** `single`

#### Input Schema

| Field                  | Type    | Required | Default | Description |
| ---------------------- | ------- | -------- | ------- | ----------- |
| `structure_file`       | file    | yes      | —       | Protein structure file (PDB or CIF format) |
| `chain_id`             | string  | yes      | —       | Chain identifier in the protein structure (e.g., 'A') |
| `stages`               | string  | yes      | —       | JSON array of docking stages, run in order — each stage docks into the previous stages' frozen ligands. Each stage: {smiles, binding_site_center?, label?}. For a covalent stage add is_covalent:true plus anchor_resname, anchor_resid and anchor_atom_name. |
| `keep_cofactors`       | string  | no       | —       | Comma-separated cofactor residue names to retain, e.g. 'ZN,NDP'; empty strips every non-standard residue. Waters go unless you add HOH. Organic cofactors are scored as NEUTRAL, so an anionic cofactor offsets absolute dG while ranking within one receptor is unaffected. Docs: https://docs.azulenelabs.com/tools/sequential_docking/ |
| `n_conformers`         | integer | no       | —       | CLASSICAL arm sample count: how many ligand conformers are enumerated in the pocket. Each is tried in many orientations (~60 trials per conformer), so classical runtime scales roughly linearly with it. Applies to EVERY stage — each one runs the same two arms. LEAVE EMPTY for the automatic default — 8 for a small molecule, 12 when cyclic-peptide/macrocycle sampling is on. A value here overrides the macrocycle default too, so leave it empty unless you mean to. Docs: https://docs.azulenelabs.com/tools/docking/. Range 1–64. |
| `n_generative_samples` | integer | no       | —       | GENERATIVE arm sample count: how many stages OpalFM diffuses. This is GPU time and is the largest cost knob on the job. Applies to EVERY stage — each one runs the same two arms. LEAVE EMPTY for the automatic default — 30 for a small molecule, 48 when cyclic-peptide/macrocycle sampling is on. Set 0 to switch the generative arm OFF and dock with the classical arm alone: much cheaper, and it gives up the arm that finds near-native poses the classical score ranks low. Docs: https://docs.azulenelabs.com/tools/docking/. Range 0–256. |
| `n_poses_per_arm`      | integer | no       | —       | OPAL-ML POOL size: how many poses from EACH arm are geometry-optimized and scored with OPAL-ML. The two arms are ranked separately by their own native metric, so the pool is 2 x this number — 3 is the 6-pose table you see in the results. Raising it searches more of what the arms already generated and costs one OPAL-ML optimization per extra pose, which is the expensive end of the job. Applies to the FINAL stage only — every earlier stage freezes exactly one winning ligand into the receptor for the next, so a wider pool there has nothing to choose between. LEAVE EMPTY for the automatic default — 3 per arm. Docs: https://docs.azulenelabs.com/tools/sequential_docking/. Range 1–10. |

##### `stages` — one entry

| Field                 | Type    | Required | Default | Description |
| --------------------- | ------- | -------- | ------- | ----------- |
| `smiles`              | string  | yes      | —       | Ligand SMILES for this stage |
| `binding_site_center` | array   | no       | —       | Pocket center for this stage. Omit to reuse the anchor-atom coordinate. |
| `label`               | string  | no       | —       | Name for this stage in the results |
| `is_covalent`         | boolean | no       | —       | Bond this ligand covalently to an anchor residue |
| `anchor_resname`      | string  | no       | —       | Three-letter name of the reactive residue. One of `SER`, `CYS`, `LYS`, `THR`, `HIS`, `TYR`. |
| `anchor_resid`        | integer | no       | —       | Sequence number of the reactive residue, in the numbering of the uploaded file |
| `anchor_atom_name`    | string  | no       | —       | Reactive atom name (e.g. OG for SER, SG for CYS) |
| `covalent_element`    | string  | no       | `C`     | Element of the atom that actually REACTS, not the warhead's most conspicuous heteroatom - a vinyl sulfone reacts at the beta-carbon, so choose C. One of `B`, `C`, `S`, `P`. |
| `bond_type`           | string  | no       | —       | Derived as &lt;warhead&gt;-&lt;target element&gt;, recomputed from the covalent inputs. Only the warhead half is read downstream (bond_type.split("-")[0]); the target half is informational. |

#### Example Input

```json
{
  "structure_file": "<local path or storage key>",
  "chain_id": "A",
  "stages": "[{\"smiles\":\"CCO\",\"binding_site_center\":[12.5,8.3,-4.1],\"label\":\"fragment\"},{\"smiles\":\"OB(O)c1ccccc1\",\"is_covalent\":true,\"anchor_resname\":\"SER\",\"anchor_resid\":70,\"anchor_atom_name\":\"OG\",\"bond_type\":\"B-O\"}]",
  "keep_cofactors": "ZN"
}
```

`structure_file` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit sequential_docking <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                     | Name                                                                   | Description |
| ------------------------------ | ---------------------------------------------------------------------- | ----------- |
| `carbonic-anhydrase-fragments` | Sulfonamide + hydrophobic fragment → carbonic anhydrase II (keep Zn²⁺) | Two-stage fragment-based co-docking into human carbonic anhydrase II (PDB 3HS4), keeping the… |
| `hsp90-fragment-growing`       | Resorcinol → isoxazole growing in the HSP90 ATP pocket                 | Two-stage fragment growing in the HSP90-alpha N-terminal ATP pocket (PDB 2XJX) — the… |
| `bcl-xl-fragment-codocking`    | Fragment co-docking → Bcl-xL BH3 groove                                | Two-stage fragment-based co-docking into the Bcl-xL BH3 groove (PDB 2YXJ) — the SAR-by-NMR… |
| `t4-lysozyme-fragments`        | Two-stage: benzene then toluene to T4 lysozyme                         | Two-stage sequential docking into the T4 lysozyme L99A cavity (PDB 4W52): dock benzene, then… |

---

### 18. Protein-Ligand Pose Refinement (`opal_ml_optimize`)

**Description:** Relaxes a pose you supply; it does not generate one. L-BFGS minimisation of the ligand or peptide binder inside the receptor under the OPAL-ML neural network potential, then a composite ΔG in kcal/mol from the ML interaction energy and MM-GBSA.

**Category:** Structure-Based Drug Design · **Docs:** <https://docs.azulenelabs.com/tools/opal_ml_optimize/> · **Submission modes:** `single`

#### Input Schema

| Field                 | Type    | Required | Default | Description |
| --------------------- | ------- | -------- | ------- | ----------- |
| `protein_file`        | file    | no       | —       | Protein structure (PDB/CIF). |
| `ligand_file`         | file    | no       | —       | Ligand structure (SDF, positioned in protein frame) |
| `ligand_resname`      | string  | no       | —       | HETATM residue name of ligand in PDB |
| `ligand_smiles`       | string  | no       | —       | OVERRIDE for the binder's chemistry. Normally leave it empty: bond orders, protonation and charges are read from the structure. Set it only when perception is wrong, or the pose is a bare heavy-atom skeleton. A SMILES whose formula disagrees with the structure is refused, not applied. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/ |
| `helm`                | string  | no       | —       | Cyclic or linear peptide binder in HELM2 notation, e.g. PEPTIDE1{R.G.D.I.N.N.N.V}$PEPTIDE1,PEPTIDE1,1:R1-8:R2$$$V2.0 — an alternative to 'ligand_smiles' for the same chemistry. Prefer it for a macrocycle: the equivalent 24-membered SMILES is not writable by hand. It names the chemistry, not the pose — this job scores the geometry you supply. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `drug_smiles`         | string  | no       | —       | Legacy name for 'ligand_smiles'. Accepted and rewritten onto 'ligand_smiles' on submission, so existing scripts, saved workflows and chained jobs keep working; new callers should use 'ligand_smiles'. Supply at most one of 'ligand_smiles' and 'helm'. |
| `chain_id`            | string  | no       | —       | Chain ID of the **receptor** — the target the binder is optimized against. See `binder_chain` for the other side of a two-chain complex. |
| `binder_chain`        | string  | no       | —       | Chain ID of the binder, as opposed to `chain_id`, which names the receptor. Supplying it switches to the peptide-complex path. **Passing a peptide binder as `chain_id` instead does not raise an error** — it takes the small-molecule path and returns an energy that is not meaningful. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/ |
| `opt_fmax`            | number  | no       | `0.05`  | Force convergence threshold (eV/Ang) for the in-pocket relaxation. Smaller means a tighter converged geometry and more steps. |
| `opt_maxiter`         | integer | no       | `200`   | Maximum LBFGS steps for the in-pocket relaxation. Reaching this limit without converging is not an error — the geometry reached is scored. |
| `flexible_radius`     | number  | no       | `0`     | Let receptor side chains within this many Angstrom of the binder relax; 0, the default, keeps the whole receptor rigid, and 4 is a sensible pocket shell. **The resulting dG is not comparable with a rigid-pocket run** — it is an induced-fit energy and comes out systematically more negative. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/. Range 0–12. |
| `flexible_residues`   | string  | no       | —       | Receptor residues to relax, as `CHAIN:RESSEQ` — for example `A:145,A:41`. Takes precedence over `flexible_radius`. Use the residue NUMBER, not its name: protonation relabels histidines to HID/HIE/HIP. Residues that do not match are reported and stay frozen. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/ |
| `flexible_backbone`   | boolean | no       | `false` | Also let the backbone of the flexible residues move, not the side chains alone. Off by default and worth leaving off — a frozen backbone is what keeps this a rotamer rearrangement rather than a slow unfolding. No effect unless flexible residues were selected. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/ |
| `crop_radius`         | number  | no       | `10`    | For a peptide binder, keep only receptor residues within this many Angstrom; 0 disables it. Not an optimisation: on a large receptor the energy difference is swamped by absolute-energy noise, which destroys ranking. Ignored on the small-molecule path. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/. Range 0–30. |
| `interior_dielectric` | number  | no       | `1`     | Solute interior dielectric for the MM-GBSA term on the peptide-binder path. **The sign of the composite is not robust to this choice** — 1, the default, is the vacuum-interior extreme. Prefer `opal_ml_dg_nnp_kcal_mol`, which this knob does not move. Ignored on the small-molecule path. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/. Range 1–20. |
| `keep_cofactors`      | string  | no       | —       | Comma-separated cofactor residue names to retain, e.g. 'ZN,NDP'; empty strips every non-standard residue. Waters go unless you add HOH. Organic cofactors are scored as NEUTRAL, so an anionic cofactor offsets absolute dG while ranking within one receptor is unaffected. Docs: https://docs.azulenelabs.com/tools/opal_ml_optimize/ |
| `extra_chains`        | string  | no       | —       | Comma-separated additional chain IDs to include (e.g. 'B' or 'B,C'). |

#### Example Input

```json
{
  "ligand_resname": "N3",
  "chain_id": "A"
}
```

#### Featured Examples

Run one with `azulene examples submit opal_ml_optimize <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                               | Name                                            | Description |
| ---------------------------------------- | ----------------------------------------------- | ----------- |
| `mpro-paxlovid`                          | Optimize Paxlovid–Mpro complex                  | GPU OPAL-ML geometry optimization of the Paxlovid–Mpro covalent complex (PDB 7RFS; bound… |
| `t4-lysozyme-benzene`                    | Optimize benzene in T4 lysozyme L99A            | GPU OPAL-ML geometry optimization of benzene bound in the engineered hydrophobic cavity of T4… |
| `cdk2-roscovitine`                       | Optimize roscovitine in CDK2                    | GPU OPAL-ML geometry optimization of the clinical CDK inhibitor roscovitine (seliciclib) bound… |
| `spsb2-cyclic-rgd-helm`                  | Optimize cyclo-RGDINNNV in SPSB2 (HELM)         | GPU OPAL-ML relaxation of a docked cyclic peptide in the SPSB2 SPRY-domain groove (PDB 5XN3)… |
| `streptavidin-cyclic-hexapeptide-smiles` | Optimize Ac-CHPQFC-NH2 in streptavidin (SMILES) | GPU OPAL-ML relaxation of a docked disulfide-cyclised hexapeptide in streptavidin (PDB 1SLD)… |

---

### 19. Protein-Ligand Interaction Energy (`opal_ml_score`)

**Description:** Single-point protein–ligand interaction energy from the OPAL-ML neural network potential, in kcal/mol, with no relaxation. Naming a `binder_chain` scores a peptide, macrocycle or stapled binder by the peptide path instead of the small-molecule one.

**Category:** Structure-Based Drug Design · **Docs:** <https://docs.azulenelabs.com/tools/opal_ml_score/> · **Submission modes:** `single`

#### Input Schema

| Field                 | Type   | Required | Default | Description |
| --------------------- | ------ | -------- | ------- | ----------- |
| `protein_file`        | file   | no       | —       | Protein structure (PDB/CIF). |
| `ligand_file`         | file   | no       | —       | Ligand structure (SDF) |
| `ligand_resname`      | string | no       | —       | HETATM residue name in PDB |
| `chain_id`            | string | no       | —       | Chain identifier of the **receptor** — the target the binder is scored against. See `binder_chain` for the other side of a two-chain complex. |
| `binder_chain`        | string | no       | —       | Chain ID of the binder, as opposed to `chain_id`, which names the receptor. Supplying it switches to the peptide-complex path. **Passing a peptide binder as `chain_id` instead does not raise an error** — it takes the small-molecule path and returns an energy that is not meaningful. Docs: https://docs.azulenelabs.com/tools/opal_ml_score/ |
| `ligand_smiles`       | string | no       | —       | OVERRIDE for the binder's chemistry. Normally leave it empty: bond orders, protonation and charges are read from the structure. Set it only when perception is wrong, or the pose is a bare heavy-atom skeleton. A SMILES whose formula disagrees with the structure is refused, not applied. Docs: https://docs.azulenelabs.com/tools/opal_ml_score/ |
| `helm`                | string | no       | —       | Cyclic or linear peptide binder in HELM2 notation, e.g. PEPTIDE1{R.G.D.I.N.N.N.V}$PEPTIDE1,PEPTIDE1,1:R1-8:R2$$$V2.0 — an alternative to 'ligand_smiles' for the same chemistry. Prefer it for a macrocycle: the equivalent 24-membered SMILES is not writable by hand. It names the chemistry, not the pose — this job scores the geometry you supply. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `drug_smiles`         | string | no       | —       | Legacy name for 'ligand_smiles'. Accepted and rewritten onto 'ligand_smiles' on submission, so existing scripts, saved workflows and chained jobs keep working; new callers should use 'ligand_smiles'. Supply at most one of 'ligand_smiles' and 'helm'. |
| `crop_radius`         | number | no       | `10`    | For a peptide binder, keep only receptor residues within this many Angstrom; 0 disables it. Not an optimisation: on a large receptor the energy difference is swamped by absolute-energy noise, which destroys ranking. Ignored on the small-molecule path. Docs: https://docs.azulenelabs.com/tools/opal_ml_score/. Range 0–30. |
| `interior_dielectric` | number | no       | `1`     | Solute interior dielectric for the MM-GBSA term on the peptide-binder path. **The sign of the composite is not robust to this choice** — 1, the default, is the vacuum-interior extreme. Prefer `opal_ml_dg_nnp_kcal_mol`, which this knob does not move. Ignored on the small-molecule path. Docs: https://docs.azulenelabs.com/tools/opal_ml_score/. Range 1–20. |
| `keep_cofactors`      | string | no       | —       | Comma-separated cofactor residue names to retain, e.g. 'ZN,NDP'; empty strips every non-standard residue. Waters go unless you add HOH. Organic cofactors are scored as NEUTRAL, so an anionic cofactor offsets absolute dG while ranking within one receptor is unaffected. Docs: https://docs.azulenelabs.com/tools/opal_ml_score/ |
| `extra_chains`        | string | no       | —       | Comma-separated additional chain IDs to include (e.g. 'B' or 'B,C'). |

#### Example Input

```json
{
  "ligand_resname": "PJE",
  "chain_id": "C"
}
```

#### Featured Examples

Run one with `azulene examples submit opal_ml_score <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                               | Name                                         | Description |
| ---------------------------------------- | -------------------------------------------- | ----------- |
| `t4-lysozyme-benzene`                    | Score benzene in T4 lysozyme L99A            | OPAL-ML single-point interaction energy for benzene bound in the T4 lysozyme L99A cavity (PDB… |
| `mpro-paxlovid`                          | Score Paxlovid–Mpro complex                  | OPAL-ML single-point interaction energy for the Paxlovid–Mpro covalent complex (PDB 7RFS… |
| `cdk2-roscovitine`                       | Score roscovitine in CDK2                    | OPAL-ML single-point interaction energy for the clinical CDK inhibitor roscovitine… |
| `spsb2-cyclic-rgd-helm`                  | Score cyclo-RGDINNNV in SPSB2 (HELM)         | OPAL-ML scoring of a docked cyclic peptide against SPSB2, with the binder's chemistry named in… |
| `streptavidin-cyclic-hexapeptide-smiles` | Score Ac-CHPQFC-NH2 in streptavidin (SMILES) | OPAL-ML scoring of a docked disulfide-cyclised hexapeptide against streptavidin, with the… |

---

### 20. Peptide 3D Structure Generation (HELM) (`peptide_structure`)

**Description:** Generate 3D structures from HELM notation for linear and cyclic peptides, including non-canonical amino acids. Supports head-to-tail cyclization, disulfide bridges, lactam bridges, and arbitrary HELM2 connections. Two methods: fast (ETKDG+MMFF) or quantum (xTB GFN2 optimization).

**Category:** Structure Generation / Sampling · **Docs:** <https://docs.azulenelabs.com/tools/peptide_structure/> · **Submission modes:** `single`

#### Input Schema

| Field              | Type    | Required | Default   | Description |
| ------------------ | ------- | -------- | --------- | ----------- |
| `helm`             | string  | yes      | —         | Peptide in HELM2 notation. Linear: PEPTIDE1{A.G.F.K.L}$$$$V2.0 - single-letter residues, dot-separated, non-canonical in brackets (e.g. [Aib], [dF]). To cyclize, add a bond in the first $-section: head-to-tail is PEPTIDE1{A.G.L.K.F}$PEPTIDE1,PEPTIDE1,5:R2-1:R1$$$V2.0. There are always exactly four $ separators, so a cyclic string ends $$$V2.0, not $$$$V2.0. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `n_conformers`     | integer | no       | `1`       | Number of conformers to generate and rank by energy. Range 1–100. |
| `conformer_method` | string  | no       | `etkdg`   | etkdg (fast, ~3s) or xtb (GFN2-xTB geometry optimization, ~30s). One of `etkdg`, `xtb`. |
| `force_field`      | string  | no       | `MMFF94s` | Force field for ETKDG optimization (ignored for xtb method). One of `MMFF94s`, `UFF`. |

#### Example Input

```json
{
  "helm": "PEPTIDE1{A.G.F.K.L}$$$$V2.0"
}
```

#### Featured Examples

Run one with `azulene examples submit peptide_structure <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID       | Name                              | Description |
| ---------------- | --------------------------------- | ----------- |
| `leu-enkephalin` | Leu-enkephalin 3D structure       | Generate a 3D structure for the opioid pentapeptide Leu-enkephalin (YGGFL) from HELM via fast… |
| `oxytocin`       | Oxytocin (disulfide) 3D structure | Generate a 3D structure for the hormone oxytocin with its native Cys1-Cys6 disulfide, from… |
| `bradykinin`     | Bradykinin (charged) 3D structure | Generate a 3D structure for the vasoactive nonapeptide bradykinin (RPPGFSPFR) from HELM… |

---

### 21. Protein Mutation Folding Stability (Physics-based ΔΔG) (`protein_mutation_ddg_fold`)

**Description:** Predict the change in folding free energy on amino-acid mutation (natural AAs + 14 ncAAs: Aib, Sar, dA/dF/dW/dY, hPhe, Hyp, mePhe, meS, meT, Nle, Orn, Phe_4F) via the Wyman two-step relative FEP cycle. Folded and unfolded legs share feflow.NonEquilibriumCyclingProtocol + Amber14SB + tip3p (with per-ncAA OpenMM XML overlays) and BAR for engine + force-field parity. The unfolded reference is a capped, context-flanked peptide built from the local sequence around the mutation site (default ±3 residues). Sign convention: ΔΔG_fold &lt; 0 ⇔ mutation stabilises the fold.

**Category:** Free Energy Methods · **Docs:** <https://docs.azulenelabs.com/tools/protein_mutation_ddg_fold/> · **Submission modes:** `single`

#### Input Schema

| Field                                | Type    | Required | Default  | Description |
| ------------------------------------ | ------- | -------- | -------- | ----------- |
| `protein_pdb`                        | file    | yes      | —        | Input protein structure (PDB). Single-chain only in v1; multi-chain ambiguous mutations are rejected. |
| `mutations`                          | string  | no       | —        | Comma-separated list of mutations of the form CHAIN:RESID[ICODE]:TARGET. Bracket-wrapped HELM2 monomers also accepted (e.g. "A:78:V,A:78:[Aib],A:78:[dF],A:78:[meS]"). Mutually exclusive with ``mutant_chain_helm``; provide one or the other. |
| `mutant_chain_helm`                  | string  | no       | —        | The mutated chain in full (N to C) in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0. Mutations are inferred by aligning it position-by-position against the chosen PDB chain, so it must be the same length as that chain. Alternative to listing `mutations`; mutually exclusive with it. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `mutant_chain_id`                    | string  | no       | `A`      | Chain id in the input PDB that ``mutant_chain_helm`` corresponds to. Default ``A``. Ignored when ``mutations`` is used directly. |
| `unfolded_flank_size`                | integer | no       | `3`      | Number of residues to keep on each side of the mutation site when building the unfolded-reference capped peptide from the input PDB. Default 3 ⇒ 7-residue window. 0 collapses to a capped single-residue (Ace-X-NMe) reference. Range 0–10. |
| `unfolded_engine`                    | string  | no       | `feflow` | Engine for the unfolded leg. 'feflow' (recommended) shares NonEquilibriumCyclingProtocol with the folded leg. 'rfe_legacy' is the original SMILES + RFECalculator path retained one release as an escape hatch. One of `feflow`, `rfe_legacy`. |
| `unfolded_relax_ns`                  | number  | no       | `0.005`  | Pre-equilibration MD duration (nanoseconds) for each context-flanked capped peptide before the FEP λ ramp. Dephases folded-context backbone torsions into a random-coil ensemble. Default 0.005 ns (=5 ps, matches the smoke equil_length_ns convention; ~1-3 s per peptide on CPU GBSA). Set 0.1 for the Aldeghi 2019 quantitative protocol. 0 runs minimisation only. (All trajectory timings in ns per stakeholder fix #3.) Minimum 0. |
| `unfolded_relax_implicit_solvent`    | boolean | no       | `true`   | If true (default), use OBC2 GBSA implicit solvent for the unfolded relaxation: ~3-10 s per peptide, no pre-solvation complications. False uses TIP3P explicit + Monte-Carlo barostat (Aldeghi 2019 protocol; required for quantitative comparison against published numbers, slower). |
| `unfolded_relax_restrained_nvt_ns`   | number  | no       | `0`      | Backbone-restrained NVT pre-equilibration duration (nanoseconds). Solvent + side chains relax around a harmonically-fixed backbone. Default 0 (skipped); Aldeghi 2019 uses 0.05 ns. Minimum 0. |
| `unfolded_relax_unrestrained_nvt_ns` | number  | no       | `0`      | Backbone-free NVT pre-equilibration duration (nanoseconds), runs after the restrained-NVT phase. Default 0 (skipped); Aldeghi 2019 uses 0.05 ns. Minimum 0. |
| `mode_preset`                        | string  | no       | `smoke`  | Single-knob preset that overrides several fields. 'smoke' (default) keeps user-supplied values. 'aldeghi_2019_quantitative' overrides equil_length_ns=5.0, n_neq_switches_per_direction=50, neq_switch_length_ns=0.05, protocol_repeats=3, unfolded_flank_size=0 (Ace-X-NMe), unfolded_relax_restrained_nvt_ns=0.05, unfolded_relax_unrestrained_nvt_ns=0.05, unfolded_relax_ns=0.1, unfolded_relax_implicit_solvent=false — the verbatim Aldeghi 2019 / Boresch & Karplus 1998 / feflow-test convention. One of `smoke`, `aldeghi_2019_quantitative`. |
| `random_seed`                        | integer | no       | `42`     | Deterministic seed for reproducible re-runs. |
| `equil_length_ns`                    | number  | no       | `5`      | Equilibration length per endpoint in nanoseconds. Default 5 ns; 0.005 is a smoke value used for plumbing tests. Minimum 0.005. |
| `n_neq_switches_per_direction`       | integer | no       | `50`     | Number of non-equilibrium switches per direction (forward + reverse). Default 50 per Aldeghi 2019. Minimum 1. |
| `protocol_repeats`                   | integer | no       | `3`      | Number of independent FEP repeats for uncertainty estimation. Minimum 1. |

#### Example Input

```json
{
  "protein_pdb": "<local path or storage key>",
  "mutations": "A:6:F"
}
```

`protein_pdb` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit protein_mutation_ddg_fold <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID          | Name                                                  | Description |
| ------------------- | ----------------------------------------------------- | ----------- |
| `model-peptide-w6f` | ddG_fold: Trp6-&gt;Phe model peptide                  | Folding free-energy change for a Trp6-&gt;Phe mutation in a 7-residue model peptide via the… |
| `chignolin-w9f`     | ddG_fold: chignolin Trp9-&gt;Phe (destabilizing)      | Folding free-energy change for a Trp9-&gt;Phe mutation in chignolin (1UAO), the 10-residue… |
| `cln025-y1g`        | ddG_fold: CLN025 Tyr1-&gt;Gly (reverts stabilization) | Folding free-energy change for a Tyr1-&gt;Gly mutation in CLN025 (5AWL), the hyperstable… |

---

### 22. Boltz-2 Structure + Affinity Prediction (`boltz_prediction`)

**Description:** Co-fold up to 12 protein chains with up to 8 cofactors and 1 ligand using Boltz-2. The minimal input is `{"proteins": [{"sequence": "..."}], "ligand": {"smiles": "..."}}` — chain IDs auto-assign (proteins → A, B, C, …; ligand → Z), MSA defaults to the public Boltz server, affinity head fires when a ligand is present, output is CIF, potentials disabled by default. Override any field explicitly. Homo-multimers are expressed by listing several `proteins` entries (one per copy) — the legacy `id: ["A", "B"]` shorthand is also accepted.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/boltz_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field          | Type    | Required | Default | Description |
| -------------- | ------- | -------- | ------- | ----------- |
| `proteins`     | array   | yes      | —       | JSON **array** of 1..12 protein chain entries — always wrap in `[...]` even for a single chain. Minimal value: `[{"sequence": "<one-letter AA string>"}]`. Per-entry: `id` auto-assigns to A, B, C, …; `msa.mode` defaults to `"server"`. |
| `ligand`       | object  | no       | —       | Optional one-ligand JSON **object** (affinity-head target). Minimal value: `{"smiles": "<SMILES>"}`. `id` auto-assigns to Z. Provide exactly one of `smiles` or `ccd`. |
| `cofactors`    | array   | no       | —       | JSON **array** of 0..8 cofactor entries. Minimal value: `[{"id": "C", "ccd": "<3-letter code>"}]`. Each requires an explicit `id` plus exactly one of `ccd` (preferred) or `smiles`. |
| `templates`    | array   | no       | —       | JSON **array** of 0..N structural templates. Minimal value: `[{"url": "<signed .pdb/.cif URL>"}]`. Each entry: `{url, chain_id?, template_id?, force?, threshold?}`. |
| `constraints`  | object  | no       | —       | Optional `{pockets: [...], bonds: [...]}` — pocket distance constraints and explicit covalent (e.g. disulfide) bonds. |
| `properties`   | object  | no       | —       | Property-head toggles. `{affinity: bool}` — defaults to `true` when a ligand is present, `false` otherwise. |
| `runtime`      | object  | no       | —       | CLI knobs. Defaults: `use_msa_server=true`, `use_potentials=false`, `no_kernels=false`, `diffusion_samples=1`, `output_format="cif"`. |
| `mode`         | string  | no       | —       | `"json"` (default) or `"raw_yaml"` for the power-user passthrough (also requires `raw_yaml_url`). One of `json`, `raw_yaml`. |
| `raw_yaml_url` | string  | no       | —       | Signed-URL pointing at a complete Boltz YAML when `mode == "raw_yaml"`. |
| `keep_dirs`    | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `proteins` — one entry

| Field      | Type   | Required | Default  | Description |
| ---------- | ------ | -------- | -------- | ----------- |
| `id`       | string | no       | —        | Chain label, e.g. A |
| `sequence` | string | yes      | —        | One-letter sequence |
| `msa.mode` | string | no       | `server` | How the MSA is built. One of `server`, `empty`, `upload`. |

##### `ligand` — one entry

| Field    | Type   | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------- |
| `smiles` | string | no       | —       | SMILES, if the ligand has no CCD code |
| `ccd`    | string | no       | —       | 3-letter PDB chemical component code, e.g. ATP |
| `id`     | string | no       | —       | Chain label; auto-assigns to Z when omitted |

##### `cofactors` — one entry

| Field    | Type   | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------- |
| `id`     | string | yes      | —       | Chain label, e.g. A |
| `ccd`    | string | no       | —       | 3-letter PDB chemical component code, e.g. ATP |
| `smiles` | string | no       | —       | SMILES, if the ligand has no CCD code |

##### `templates` — one entry

| Field      | Type   | Required | Default | Description |
| ---------- | ------ | -------- | ------- | ----------- |
| `url`      | string | yes      | —       | Signed .pdb / .cif URL |
| `chain_id` | string | no       | —       | Chain this template applies to |

#### Example Input

```json
{
  "proteins": [
    {
      "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK"
    }
  ],
  "ligand": {
    "smiles": "CC(=O)Oc1ccccc1C(=O)O"
  },
  "properties": {
    "affinity": true
  }
}
```

#### Featured Examples

Run one with `azulene examples submit boltz_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                     | Name                                    | Description |
| ------------------------------ | --------------------------------------- | ----------- |
| `boltz-t4-toluene`             | T4 lysozyme L99A + toluene (affinity)   | T4 lysozyme L99A co-folded de novo with toluene, firing Boltz-2's affinity head on the… |
| `boltz-dhfr-trimethoprim`      | E. coli DHFR + NADPH + trimethoprim     | E. coli DHFR co-folded with its NADPH cofactor and the inhibitor trimethoprim under explicit… |
| `boltz-t4-template`            | T4 L99A + toluene (template-guided)     | Template-guided counterpart to t4-toluene: the same L99A + toluene affinity job folded onto… |
| `boltz-hiv-protease-indinavir` | HIV-1 protease dimer + indinavir        | HIV-1 protease homodimer co-folded with indinavir, demonstrating C2-symmetric interface… |
| `boltz-fkbp-frb-rapamycin`     | FKBP12–FRB + rapamycin (molecular glue) | The rapamycin molecular glue co-folded with the FKBP12 + FRB heterodimer — a compact… |
| `boltz-ubiquitin-ensemble`     | Ubiquitin 20-model ensemble             | Pure structure prediction of ubiquitin with 20 diffusion samples, exporting a 20-model… |

---

### 23. Rank protein-protein interfaces using Opal (`opal_ppi`)

**Description:** Predict and rank candidate protein-protein interfaces from two protein sequences. Returns representative complex structures, interface-confidence scores, and interface residues for follow-up analysis. Returns up to 5 interfaces by default; combined chain length is capped at 1500 residues.

**Category:** Co-folding · **Docs:** <https://docs.azulenelabs.com/tools/opal_ppi/> · **Submission modes:** `single`

#### Input Schema

| Field                 | Type    | Required | Default | Description |
| --------------------- | ------- | -------- | ------- | ----------- |
| `protein_a`           | object  | yes      | —       | First protein chain. Prefer the binding DOMAIN over the full-length UniProt entry: long disordered tails depress receptor pTM and increase runtime without improving the interface. |
| `protein_b`           | object  | yes      | —       | Second protein chain. Whichever of the two chains is shorter is treated as the binder when the binding-affinity estimate is computed. |
| `n_surfaces`          | integer | no       | —       | Number of representative binding surfaces to return (1..20). Default 5. |
| `n_diffusion_samples` | integer | no       | —       | Structure-prediction diffusion samples to run before clustering (2..50). Default 15. |
| `runtime`             | object  | no       | —       | PPI runtime knobs. `{use_msa_server: bool=true, use_potentials: bool=false, no_kernels: bool=false}`. Structures are always returned as PDB. |
| `keep_dirs`           | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `protein_a` — one entry

| Field      | Type   | Required | Default  | Description |
| ---------- | ------ | -------- | -------- | ----------- |
| `sequence` | string | yes      | —        | One-letter amino-acid sequence of the first chain. |
| `id`       | string | no       | `A`      | Chain label. Defaults to A. |
| `msa.mode` | string | no       | `server` | How this chain's MSA is built. Keep `server`: single-sequence chains fold badly, which corrupts the interface you are trying to score. One of `server`, `empty`, `upload`. |

##### `protein_b` — one entry

| Field      | Type   | Required | Default  | Description |
| ---------- | ------ | -------- | -------- | ----------- |
| `sequence` | string | yes      | —        | One-letter amino-acid sequence of the second chain. |
| `id`       | string | no       | `B`      | Chain label. Defaults to B. |
| `msa.mode` | string | no       | `server` | How this chain's MSA is built. Keep `server`: single-sequence chains fold badly, which corrupts the interface you are trying to score. One of `server`, `empty`, `upload`. |

#### Example Input

```json
{
  "protein_a": {
    "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK"
  },
  "protein_b": {
    "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK"
  },
  "n_surfaces": 5,
  "n_diffusion_samples": 15
}
```

#### Featured Examples

Run one with `azulene examples submit opal_ppi <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                 | Name                                | Description |
| -------------------------- | ----------------------------------- | ----------- |
| `opal-ppi-barnase-barstar` | Barnase-Barstar interface           | Opal protein-protein interface ranking for the classic barnase-barstar complex. |
| `opal-ppi-pd1-pdl1`        | PD-1 / PD-L1 immune checkpoint      | Opal protein-protein interface ranking for the PD-1 / PD-L1 immune checkpoint (PDB 4ZQK) — the… |
| `opal-ppi-kras-raf1-rbd`   | KRAS / RAF1-RBD oncogenic interface | Opal protein-protein interface ranking for the oncogenic RAS-effector interaction KRAS /… |

---

### 24. Macrocycle and Cyclic Peptide Binding Prediction (`boltz_macrocycle`)

**Description:** Folds a macrocyclic or stapled peptide against a receptor and scores the interface; the binder is a peptide chain, not a ligand SMILES. Receptor plus binder is capped at 1500 residues. Poses are sampled under steering potentials and ranked by interface confidence, with an experimental `affinity_pkd` (higher = tighter) that separates strong binders from weak rather than ranking close analogs. Where the binder's chemistry allows, each pose also carries an OPAL-ML interaction energy — `opal_ml_dg_nnp_kcal_mol`, kcal/mol, with `opal_ml_dg_mmgbsa_kcal_mol` and their sum `opal_ml_dg_kcal_mol` — not a calibrated binding free energy. A binder whose residues have no protonation template reports no energy rather than an unreliable one; the affinity estimate and the interface scores are unaffected. `opal_ml_inputs` feeds Protein-Ligand Interaction Energy and Protein-Ligand Pose Refinement.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/macrocycle_affinity/> · **Submission modes:** `single`

#### Input Schema

| Field                 | Type    | Required | Default | Description |
| --------------------- | ------- | -------- | ------- | ----------- |
| `receptor`            | object  | yes      | —       | Target protein chain — a JSON object, e.g. `{"sequence": "<one-letter AA string>"}`. **Trim the receptor to the binding domain.** A full-length sequence folds far worse and takes the scored interface down with it, quietly; it is the biggest quality lever on this tool. |
| `binder`              | object  | yes      | —       | Macrocyclic or stapled peptide binder — a JSON object expressed as a peptide CHAIN, not a ligand SMILES. Minimal value: `{"sequence": "<one-letter AA string>"}`. Non-standard residues go in `modifications`, the crosslink itself in `bonds`. |
| `modifications`       | array   | no       | —       | Non-standard residues on the binder, as `[{position, ccd}]` — 1-based positions into `binder.sequence`, each replaced by the named PDB chemical component. Leave empty for an all-canonical peptide. |
| `bonds`               | array   | no       | —       | Explicit covalent crosslinks on the binder: `[{kind, atom1: {residue, atom}, atom2: {residue, atom}}]`, residue indices 1-based into `binder.sequence`. Staples, disulfides, lactams and thioethers belong here and NOT in `binder.cyclic`. |
| `n_poses`             | integer | no       | `5`     | Number of diverse representative poses to return (1..20). Default 5. Range 1–20. |
| `n_diffusion_samples` | integer | no       | `15`    | Diffusion samples to generate before ranking and clustering (2..50). Default 15. Wall-clock and cost scale roughly linearly with this. Range 2–50. |
| `ligand_arm`          | boolean | no       | `true`  | Also co-fold the binder as a LIGAND from its own SMILES, so Protein-Ligand Interaction Energy and Protein-Ligand Pose Refinement receive a declared molecular graph instead of one re-perceived from coordinates — perception mangles stapled peptides. Turning it off returns the single fold and roughly halves the runtime. |
| `ligand_file`         | file    | no       | —       | The binder as an SDF or MOL file, read for its CHEMISTRY and never as a starting conformer. This is what a **Peptide Structure** result hands over — pass its `structure_sdf_url.download_url`. Checked against the sequence, with a warning if they describe different molecules. Accepts `.sdf,.mol`. |
| `ligand_smiles`       | string  | no       | —       | The binder's chemistry as a SMILES, for the ligand fold. Optional: it is otherwise assembled from `binder.sequence`, `modifications` and `bonds` via the same CCD entries. A SMILES you supply is used verbatim and is not re-charged at pH 7.4. |
| `helm`                | string  | no       | —       | The binder in HELM2 notation, naming its CHEMISTRY for the ligand fold — never a starting conformer. Templating a macrocycle on a generated conformer was measured and it hurts: on the PD-L1 example the binder went from 1.36 A to 3.38 A off the deposited structure. Full syntax: https://docs.azulenelabs.com/tools/peptide_structure/ |
| `runtime`             | object  | no       | —       | Runtime knobs. `{use_msa_server: bool=true, use_potentials: bool=true, no_kernels: bool=false}`. `use_potentials` steers the diffusion so poses come out clash-free and covalently sane; it is on by default and costs roughly 3x the sampling time. |
| `templates`           | array   | no       | —       | Structural templates for the BINDER chain, as `[{"url", "chain_id", "force", "threshold"}]`. **Set `force` true or the template barely does anything.** PDB or CIF only, never SDF, and template a conformation you trust: a generated one made accuracy worse, not better. |
| `keep_dirs`           | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `receptor` — one entry

| Field      | Type   | Required | Default  | Description |
| ---------- | ------ | -------- | -------- | ----------- |
| `sequence` | string | yes      | —        | One-letter sequence of the target protein |
| `id`       | string | no       | `A`      | Chain label; defaults to A |
| `msa.mode` | string | no       | `server` | How the receptor MSA is built. One of `server`, `empty`, `upload`. |

##### `binder` — one entry

| Field      | Type    | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ----------- |
| `sequence` | string  | yes      | —       | One-letter sequence of the peptide binder |
| `id`       | string  | no       | `B`     | Chain label; defaults to B |
| `cyclic`   | boolean | no       | `false` | HEAD-TO-TAIL BACKBONE CLOSURE ONLY — the peptide's own N-terminus amide-bonded to its own C-terminus. Leave this OFF for stapled, disulfide-bridged, lactam-bridged and thioether peptides: those are side-chain crosslinks on a LINEAR backbone and belong in `bonds`, not here. Most macrocyclic peptides are not head-to-tail. Setting it wrongly is silent: it changes the residue positional encoding (the model wraps position N back to position 1) without any error, so the pose comes back looking plausible and is wrong. |

##### `modifications` — one entry

| Field      | Type    | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ----------- |
| `position` | integer | yes      | —       | 1-based residue index into the binder sequence. Minimum 1. |
| `ccd`      | string  | yes      | —       | PDB chemical-component (CCD) code for the replacement residue. CCD CODES ARE NOT GUESSABLE FROM TRIVIAL NAMES — look the code up in the PDB chemical component dictionary before using it. Two codes that read like the obvious answer and are not: `CBA` is a pyridoxal-phosphate adduct, NOT cyclobutyl-alanine (that is `2JH`); `AHX` is an AMP conjugate, NOT 6-aminohexanoic acid (that is `ACA`). A wrong-but-real code is accepted and folded, so the job succeeds with the wrong chemistry. |

##### `bonds` — one entry

| Field           | Type    | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ----------- |
| `kind`          | string  | no       | —       | Chemistry of the crosslink. Sets the default atom names and the bond order. One of `staple`, `disulfide`, `lactam`, `thioether`, `head_to_tail`, `sidechain`. |
| `atom1.residue` | integer | yes      | —       | 1-based residue index of the first crosslink partner. Minimum 1. |
| `atom1.atom`    | string  | no       | —       | PDB atom name on residue 1 (e.g. CZ, CJ, SG). Defaults from `kind`. |
| `atom2.residue` | integer | yes      | —       | 1-based residue index of the second crosslink partner. Minimum 1. |
| `atom2.atom`    | string  | no       | —       | PDB atom name on residue 2 (e.g. CZ, CJ, SG). Defaults from `kind`. |

##### `templates` — one entry

| Field       | Type    | Required | Default | Description |
| ----------- | ------- | -------- | ------- | ----------- |
| `url`       | file    | yes      | —       | Conformer structure — upload a PDB or CIF file. Never an SDF: structural templates are read as PDB or CIF only. |
| `chain_id`  | string  | no       | —       | Chain this template applies to. Must be the binder chain — templating the receptor would replace the structure you asked to dock against. |
| `force`     | boolean | no       | `false` | Restrain the binder to this template during sampling. Off by default, and off means the template has almost no effect — leave it off only if you want the structure as a hint rather than a constraint. |
| `threshold` | number  | no       | `1.5`   | How far each residue may drift from the template, in Ångström, when `force` is on. 1.0–1.5 is the useful range: tightening to 0.5 bought 0.02 Å and cost interface confidence. |

#### Example Input

```json
{
  "receptor": {
    "sequence": "MCNTNMSVPTDGAVTTSQIPASEQETLVRPKPLLLKLLKSVGAQKDTYTMKEVLFYLGQYIMTKRLYDEKQQHIVYCSNDLLGDLFGVPSFSVKEHRKIYTMIYRNLVVVNQQESSDSGTSVSEN"
  },
  "binder": {
    "sequence": "TSFAHYWALLA",
    "cyclic": false
  },
  "modifications": [
    {
      "position": 4,
      "ccd": "L4R"
    },
    {
      "position": 11,
      "ccd": "MH8"
    }
  ],
  "bonds": [
    {
      "kind": "staple",
      "atom1": {
        "residue": 4,
        "atom": "CJ"
      },
      "atom2": {
        "residue": 11,
        "atom": "CZ"
      }
    }
  ],
  "n_poses": 5,
  "n_diffusion_samples": 15
}
```

#### Featured Examples

Run one with `azulene examples submit boltz_macrocycle <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                          | Name                                                | Description |
| ----------------------------------- | --------------------------------------------------- | ----------- |
| `boltz-macrocycle-mdm2-stapled-p53` | MDM2 + stapled p53 helix (i,i+7 hydrocarbon staple) | An i,i+7 all-hydrocarbon stapled p53 analog against the MDM2 p53-binding domain — the textbook… |
| `boltz-macrocycle-pdl1-cyclic`      | PD-L1 + head-to-tail cyclic peptide (PDB 7OUN)      | The co-crystallised macrocycle from PDB 7OUN against the PD-L1 IgV ectodomain. This is the one… |
| `boltz-macrocycle-igg-fc-disulfide` | IgG1 Fc + Fc-III disulfide-cyclised peptide         | The Fc-III cyclic peptide against the IgG1 Fc CH2–CH3 interface (PDB 5DI8 family). Disulfide… |

---

### 25. Chai-1 Complex Structure Prediction (`chai_prediction`)

**Description:** All-atom co-folding with Chai-1 (Apache-2.0). Supports protein, RNA, DNA, and small-molecule chains; MSA-free via ESM embeddings or MSA-augmented; constraint and template inputs match the AF3 family.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/chai_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field           | Type    | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ----------- |
| `chains`        | array   | yes      | —       | 1..12 chains. Each: `{id, sequence, type}` where type is one of protein \| rna \| dna \| glycan (default protein). `id` may be a list for a homo-multimer. Flat shape (no `request` wrapper), matching boltz_prediction. |
| `ligands`       | array   | no       | —       | 0..8 ligands / cofactors. Each: `{id, ccd}` or `{id, smiles}` (exactly one of ccd / smiles). |
| `templates`     | array   | no       | —       | Optional structural templates: `{url, chain_id?}` referencing a signed `.pdb` / `.cif` upload. |
| `runtime`       | object  | no       | —       | Chai-1 runtime knobs. Defaults: `use_esm_embeddings=true`, `use_msa_server=false`, `low_memory=true`, `num_diffn_samples=5`, `output_format="cif"`. |
| `mode`          | string  | no       | —       | `"json"` (default) or `"raw_fasta"` for the power-user FASTA passthrough (also requires `raw_fasta_url`). One of `json`, `raw_fasta`. |
| `raw_fasta_url` | string  | no       | —       | Signed-URL pointing at a complete Chai FASTA when `mode == "raw_fasta"`. |
| `keep_dirs`     | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `chains` — one entry

| Field      | Type   | Required | Default   | Description |
| ---------- | ------ | -------- | --------- | ----------- |
| `id`       | string | yes      | —         | Chain label, e.g. A. A list such as ["A","B"] repeats the same sequence as a homo-multimer. |
| `sequence` | string | yes      | —         | One-letter sequence |
| `type`     | string | no       | `protein` | Polymer class. For protein/rna/dna, sequence is the one-letter sequence; for glycan it is a Chai glycan string (e.g. NAG(4-1 NAG)), not residues. Small molecules and cyclic peptides go in ligands as SMILES. One of `protein`, `rna`, `dna`, `glycan`, `cyclic`. |

##### `ligands` — one entry

| Field    | Type   | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------- |
| `id`     | string | yes      | —       | Chain label, e.g. A |
| `ccd`    | string | no       | —       | 3-letter PDB chemical component code, e.g. ATP |
| `smiles` | string | no       | —       | SMILES, if the ligand has no CCD code |

##### `templates` — one entry

| Field      | Type   | Required | Default | Description |
| ---------- | ------ | -------- | ------- | ----------- |
| `url`      | string | yes      | —       | Signed .pdb / .cif URL |
| `chain_id` | string | no       | —       | Chain this template applies to |

#### Example Input

```json
{
  "chains": [
    {
      "id": "A",
      "type": "protein",
      "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK"
    }
  ],
  "runtime": {
    "use_esm_embeddings": true,
    "num_diffn_samples": 5,
    "output_format": "cif"
  },
  "keep_dirs": true
}
```

#### Featured Examples

Run one with `azulene examples submit chai_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID          | Name                              | Description |
| ------------------- | --------------------------------- | ----------- |
| `chai-abl-imatinib` | ABL1 kinase + imatinib (MSA-free) | MSA-free Chai-1 co-fold of the ABL1 kinase domain with imatinib (Gleevec) straight from… |
| `chai-u1a-rna`      | U1A protein + U1 snRNA hairpin    | All-atom protein-RNA co-fold of the U1A spliceosomal protein bound to its U1 snRNA stem-loop… |
| `chai-er-estradiol` | ER-α LBD homodimer + estradiol    | ER-alpha ligand-binding-domain homodimer (one sequence over two chains) co-folded MSA-free… |

---

### 26. OpenFold3 Complex Structure Prediction (`openfold3_prediction`)

**Description:** AF3-parity all-atom structure prediction with OpenFold3 (Apache-2.0). Within experimental error of AlphaFold3 on CASP16 monomers and the only open model matching AF3 on RNA.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/openfold3_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field               | Type    | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ----------- |
| `chains`            | array   | yes      | —       | The molecules to fold, given as a JSON list of 1–12 chains. Each chain is an object with: `id` (a chain label like "A"; use a list such as ["A","B"] to repeat the same sequence as a homo-multimer), `sequence` (the one-letter sequence), and `type` — one of "protein", "rna", or "dna" (defaults to "protein"). Edit the example shown in the box. Example: [{"id":"A","type":"protein","sequence":"MNIF..."}]. |
| `ligands`           | array   | no       | —       | Optional small molecules / cofactors to co-fold (0–8), as a JSON list. Each is an object with an `id` plus EITHER `ccd` (a 3-letter PDB chemical-component code, e.g. "ATP") OR `smiles` (a SMILES string). Leave empty if there are no ligands. Example: [{"id":"L1","ccd":"ATP"}]. |
| `bonded_atom_pairs` | array   | no       | —       | Explicit covalent / disulfide bonds: `[{chain_id_a, residue_a, atom_a, chain_id_b, residue_b, atom_b}]`. |
| `name`              | string  | no       | —       | Job name written into the AF3 JSON (default `openfold3_job`). |
| `runtime`           | object  | no       | —       | OpenFold3 runtime knobs. Defaults: `use_deepspeed_evo_attention=true`, `num_diffn_samples=5`, `num_recycles=3`, `precision="bf16"`, `output_format="cif"`. |
| `mode`              | string  | no       | —       | `"json"` (default) or `"raw_af3_json"` for the power-user AF3-JSON passthrough (also requires `raw_af3_url`). One of `json`, `raw_af3_json`. |
| `raw_af3_url`       | string  | no       | —       | Signed-URL pointing at a complete AF3 input JSON when `mode == "raw_af3_json"`. |
| `user_ccd`          | string  | no       | —       | Optional user-supplied CCD entries in mmCIF format (raw text) for non-standard ligands. |
| `keep_dirs`         | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `chains` — one entry

| Field      | Type   | Required | Default   | Description |
| ---------- | ------ | -------- | --------- | ----------- |
| `id`       | string | yes      | —         | Chain label, e.g. A. A list such as ["A","B"] repeats the same sequence as a homo-multimer. |
| `sequence` | string | yes      | —         | One-letter sequence |
| `type`     | string | no       | `protein` | Polymer class. For protein/rna/dna, sequence is the one-letter sequence; for glycan it is a Chai glycan string (e.g. NAG(4-1 NAG)), not residues. Small molecules and cyclic peptides go in ligands as SMILES. One of `protein`, `rna`, `dna`. |

##### `ligands` — one entry

| Field    | Type   | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------- |
| `id`     | string | yes      | —       | Chain label, e.g. A |
| `ccd`    | string | no       | —       | 3-letter PDB chemical component code, e.g. ATP |
| `smiles` | string | no       | —       | SMILES, if the ligand has no CCD code |

##### `bonded_atom_pairs` — one entry

| Field        | Type    | Required | Default | Description |
| ------------ | ------- | -------- | ------- | ----------- |
| `chain_id_a` | string  | yes      | —       | First chain |
| `residue_a`  | integer | yes      | —       | First residue number |
| `atom_a`     | string  | yes      | —       | First atom name, e.g. SG |
| `chain_id_b` | string  | yes      | —       | Second chain |
| `residue_b`  | integer | yes      | —       | Second residue number |
| `atom_b`     | string  | yes      | —       | Second atom name, e.g. SG |

#### Example Input

```json
{
  "chains": [
    {
      "id": "A",
      "type": "protein",
      "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK"
    }
  ],
  "name": "of3-single-protein",
  "runtime": {
    "num_diffn_samples": 5,
    "output_format": "cif"
  },
  "keep_dirs": true
}
```

#### Featured Examples

Run one with `azulene examples submit openfold3_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                    | Name                                       | Description |
| ----------------------------- | ------------------------------------------ | ----------- |
| `openfold3-trna-phe`          | Yeast tRNA-Phe (pure RNA)                  | Pure-RNA prediction of the L-shaped yeast tRNA-Phe fold from sequence alone — where… |
| `openfold3-ca2-acetazolamide` | Carbonic anhydrase II + acetazolamide (Zn) | AF3-style all-atom co-fold of human carbonic anhydrase II with its catalytic zinc and the… |
| `openfold3-engrailed-dna`     | Engrailed homeodomain + dsDNA              | Protein-DNA co-fold of the Drosophila engrailed homeodomain with its double-stranded DNA… |

---

### 27. OpenFold2 Protein Structure Prediction (`openfold2_prediction`)

**Description:** Single-chain and multimer protein structure prediction with OpenFold2 (Apache-2.0). OpenFold2 weights and architecture.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/openfold2_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field           | Type    | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ----------- |
| `proteins`      | array   | yes      | —       | 1..12 protein chains. Each: `{id, sequence, msa:{mode}}` where msa.mode is one of server \| empty \| upload. `id` may be a list for a homo-multimer. Flat shape (no `request` wrapper), matching boltz_prediction. |
| `templates`     | array   | no       | —       | Optional structural templates: `{url, chain_id?}`. |
| `runtime`       | object  | no       | —       | OpenFold2 runtime knobs. Defaults: `use_msa_server=true`, `long_sequence_inference=true`, `use_deepspeed_evo_attention=true`, `num_recycles=3`, `output_format="pdb"`. |
| `mode`          | string  | no       | —       | `"json"` (default) or `"raw_fasta"` for the power-user FASTA passthrough (also requires `raw_fasta_url`). One of `json`, `raw_fasta`. |
| `raw_fasta_url` | string  | no       | —       | Signed-URL pointing at a complete FASTA when `mode == "raw_fasta"`. |
| `keep_dirs`     | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `proteins` — one entry

| Field      | Type   | Required | Default | Description |
| ---------- | ------ | -------- | ------- | ----------- |
| `id`       | string | yes      | —       | Chain label, e.g. A. A list such as ["A","B"] repeats the same sequence as a homo-multimer. |
| `sequence` | string | yes      | —       | One-letter sequence |
| `msa.mode` | string | no       | `empty` | How the MSA is built. upload is the only mode that currently gives OpenFold2 an alignment (supply msa.upload_url). server is NOT YET IMPLEMENTED and currently behaves as empty; it is still accepted so existing payloads keep working. empty is single-sequence inference - substantially less accurate than MSA-based AF2 for most natural proteins, and pLDDT/pTM are correspondingly less meaningful. The default is empty because that is what actually runs - defaulting to server would name the reassuring mode while delivering the worst one. One of `server`, `empty`, `upload`. |

##### `templates` — one entry

| Field      | Type   | Required | Default | Description |
| ---------- | ------ | -------- | ------- | ----------- |
| `url`      | string | yes      | —       | Signed .pdb / .cif URL |
| `chain_id` | string | no       | —       | Chain this template applies to |

#### Example Input

```json
{
  "proteins": [
    {
      "id": "A",
      "sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK",
      "msa": {
        "mode": "server"
      }
    }
  ],
  "runtime": {
    "use_msa_server": true,
    "output_format": "pdb"
  },
  "keep_dirs": true
}
```

#### Featured Examples

Run one with `azulene examples submit openfold2_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID             | Name                           | Description |
| ---------------------- | ------------------------------ | ----------- |
| `openfold2-lysozyme`   | Hen egg-white lysozyme monomer | OpenFold2 monomer prediction of hen egg-white lysozyme. NOTE: runs single-sequence today -… |
| `openfold2-luciferase` | Firefly luciferase (~550 aa)   | Long single-chain firefly luciferase (~550 residues) exercising OpenFold2's long-sequence path… |

---

### 28. ProteinMPNN Sequence Design (Inverse Folding) (`mpnn_design`)

**Description:** Design new amino-acid sequences that fold to a backbone structure you provide (inverse folding). Upload a structure and get back several candidate sequences, each with confidence scores and how much it recovers the native sequence. Pick the model that fits your goal: ProteinMPNN (general purpose, protein-only inputs), LigandMPNN (when the backbone includes ligands, nucleic acids, or metal ions you want the design to respect), or SolubleMPNN (when you want to improve the solubility of a soluble protein).

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/mpnn_design/> · **Submission modes:** `single`

#### Input Schema

| Field                             | Type    | Required | Default        | Description |
| --------------------------------- | ------- | -------- | -------------- | ----------- |
| `mode`                            | string  | yes      | `design`       | Selects this design task. Leave as the default. One of `design`. |
| `model_type`                      | string  | no       | `protein_mpnn` | Which model to use: "protein_mpnn" (default, general purpose), "ligand_mpnn" (accounts for ligands, nucleic acids, or metal ions in the structure), or "soluble_mpnn" (biased toward more soluble sequences). One of `protein_mpnn`, `ligand_mpnn`, `soluble_mpnn`. |
| `pdb_file`                        | file    | no       | —              | The backbone structure to redesign — upload a PDB or CIF file. This is the main input; provide either this or the advanced pdb field, not both. Accepts `.pdb,.cif`. |
| `pdb`                             | object  | no       | —              | Advanced/API alternative to uploading a file: supply the backbone as {"inline": "&lt;raw PDB text&gt;"} or {"url": "&lt;signed https URL&gt;"}. Most users should upload via pdb_file instead. Provide one or the other, not both. |
| `chains_to_design`                | array   | no       | —              | Which chains to redesign, by chain ID (e.g. ["A"]). Leave empty to redesign every chain. |
| `fixed_positions`                 | object  | no       | —              | Positions to keep at their original amino acid, listed per chain. A position that is not in the file is SILENTLY IGNORED - it will not be held fixed and the job still reports success. Residue numbers are as written in the uploaded file (author numbering), not a 1-based count from the start of the chain — the two differ whenever a construct starts at something other than 1 or has gaps. |
| `redesign_positions`              | object  | no       | —              | Positions to redesign, listed per chain, leaving every other position fixed. A position that is not in the file is SILENTLY IGNORED, leaving it fixed instead of redesigned. Residue numbers are as written in the uploaded file (author numbering), not a 1-based count from the start of the chain — the two differ whenever a construct starts at something other than 1 or has gaps. For a given chain, use this or fixed_positions, not both. |
| `bias_aa`                         | object  | no       | —              | Nudge the design toward or away from specific amino acids at every designed position. Keys are one-letter amino-acid codes; positive values favour an amino acid, negative values disfavour it. |
| `omit_aa`                         | array   | no       | —              | Amino acids to never use at any designed position (e.g. exclude cysteine). |
| `num_seq_per_target`              | integer | no       | `8`            | How many candidate sequences to design (1 to 1024). Default 8. Range 1–1024. |
| `sampling_temp`                   | number  | no       | `0.1`          | How adventurous the design is (0.01 to 2.0). Default 0.1. Lower values stay closer to the most likely, native-like sequence; higher values give more diverse but riskier designs. Range 0.01–2. |
| `batch_size`                      | integer | no       | `1`            | How many sequences are computed together per pass (1 to 128). Default 1. A performance knob that does not change the results. Range 1–128. |
| `seed`                            | integer | no       | `37`           | Random seed. Default 37. Use the same seed to reproduce a run; change it to get a different set of designs. Minimum 0. |
| `checkpoint`                      | string  | no       | —              | Advanced: a specific model checkpoint to use instead of the default for the chosen model. |
| `parse_atoms_with_zero_occupancy` | boolean | no       | `false`        | Whether to keep atoms marked with zero occupancy in the input structure. Off by default (they are ignored). Turn on only if your structure stores meaningful atoms at zero occupancy that you want included. |
| `keep_dirs`                       | boolean | no       | `true`         | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

#### Example Input

```json
{
  "mode": "design",
  "model_type": "protein_mpnn",
  "pdb_file": "<local path or storage key>",
  "chains_to_design": [
    "A"
  ],
  "num_seq_per_target": 4,
  "sampling_temp": 0.1
}
```

`pdb_file` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit mpnn_design <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                    | Name                                  | Description |
| ----------------------------- | ------------------------------------- | ----------- |
| `mpnn-design-crambin`         | Crambin inverse folding (ProteinMPNN) | ProteinMPNN inverse folding of the crambin (1CRN) backbone — 8 sequences at low temperature… |
| `mpnn-design-villin-hp36`     | Villin HP36 redesign (SolubleMPNN)    | SolubleMPNN redesign of villin headpiece HP36 (1VII) with the three core phenylalanines fixed… |
| `mpnn-design-t4-l99a-benzene` | T4 L99A + benzene (LigandMPNN)        | LigandMPNN design of T4 lysozyme L99A (1L83) conditioned on the bound benzene ligand in the… |

---

### 29. ThermoMPNN Mutation Stability (ML-based ΔΔG) (`mpnn_stability`)

**Description:** Predict how mutations change a protein's folding stability (ΔΔG, in kcal/mol) from its structure, using ThermoMPNN. Negative values mean the mutation is predicted to stabilize the fold, positive values mean it destabilizes. Either score a specific list of mutations, or scan a stretch of a chain to try every possible amino-acid substitution (site saturation). Use it to find stabilizing mutations or to flag risky ones before testing.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/mpnn_stability/> · **Submission modes:** `single`

#### Input Schema

| Field        | Type    | Required | Default         | Description |
| ------------ | ------- | -------- | --------------- | ----------- |
| `mode`       | string  | yes      | `stability`     | Selects this stability task. Leave as the default. One of `stability`. |
| `pdb_file`   | file    | no       | —               | The protein structure to score — upload a PDB or CIF file. This is the main input; provide either this or the advanced pdb field, not both. Accepts `.pdb,.cif`. |
| `pdb`        | object  | no       | —               | Advanced/API alternative to uploading a file: supply the structure as {"inline": "&lt;raw PDB text&gt;"} or {"url": "&lt;signed https URL&gt;"}. Most users should upload via pdb_file instead. Provide one or the other, not both. |
| `mutations`  | array   | no       | —               | A specific list of mutations to score. Each entry is {chain, position, from_aa, to_aa}. Residue numbers are as written in the uploaded file (author numbering), not a 1-based count from the start of the chain — the two differ whenever a construct starts at something other than 1 or has gaps. from_aa is checked against the residue actually at that position; a mismatch returns no predictions plus a warning naming what was requested. Use this or saturation, not both. |
| `saturation` | object  | no       | —               | Scan a region instead of a fixed list: give {chain, start, end} (inclusive) and every possible amino-acid substitution at every position in that window is scored. Residue numbers are as written in the uploaded file (author numbering), not a 1-based count from the start of the chain — the two differ whenever a construct starts at something other than 1 or has gaps. Use this or mutations, not both. |
| `checkpoint` | string  | no       | `thermompnn_v1` | Advanced: a specific model checkpoint to use instead of the default. |
| `batch_size` | integer | no       | `256`           | How many mutations are scored together per pass (1 to 4096). Default 256. A performance knob that does not change the results. Range 1–4096. |
| `keep_dirs`  | boolean | no       | `true`          | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

##### `mutations` — one entry

| Field      | Type    | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ----------- |
| `chain`    | string  | yes      | —       | Chain the residue is in |
| `position` | integer | yes      | —       | 1-based position (the first residue is 1) |
| `from_aa`  | string  | yes      | —       | Wild-type residue. One of `A`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `K`, `L`, `M`, `N`, `P`, `Q`, `R`, `S`, `T`, `V`, `W`, `Y`. |
| `to_aa`    | string  | yes      | —       | Substituted residue. One of `A`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `K`, `L`, `M`, `N`, `P`, `Q`, `R`, `S`, `T`, `V`, `W`, `Y`. |

#### Example Input

```json
{
  "mode": "stability",
  "pdb_file": "<local path or storage key>",
  "mutations": [
    {
      "chain": "A",
      "position": 1,
      "from_aa": "M",
      "to_aa": "V"
    }
  ]
}
```

`pdb_file` takes a local path — the SDK uploads it and substitutes the storage key — or a storage key you already have. Check the Required column above for which of them you have to supply.

#### Featured Examples

Run one with `azulene examples submit mpnn_stability <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                   | Name                                | Description |
| ---------------------------- | ----------------------------------- | ----------- |
| `mpnn-stability-ubiquitin`   | Ubiquitin core mutations (ΔΔG)      | ThermoMPNN ddG for three explicit ubiquitin (1UBQ) core mutations — I3V, V5A, L8A. |
| `mpnn-stability-crambin`     | Crambin site-saturation sweep (ΔΔG) | ThermoMPNN site-saturation sweep over crambin (1CRN) positions 5-9 (every non-native AA, 95… |
| `mpnn-stability-villin-hp36` | Villin HP36 single mutation (ΔΔG)   | ThermoMPNN ddG for the single villin headpiece HP36 (1VII) core mutation F47A. |

---

### 30. ESM-2 Protein Sequence Embeddings (`esm2_embed`)

**Description:** Turn protein sequences into ESM-2 embeddings — numeric vectors that capture each protein's properties for use in downstream machine learning, similarity search, or clustering. Optionally also predict residue-residue contact maps. Submit one or many sequences in a single run.

**Category:** Protein Embeddings · **Docs:** <https://docs.azulenelabs.com/tools/esm2_embed/> · **Submission modes:** `single`

#### Input Schema

| Field             | Type    | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ----------- |
| `sequences`       | array   | yes      | —       | The protein sequences to embed, as one-letter amino acids — one per line, or paste FASTA. Up to 64 sequences per job, each up to 2048 residues. Embeddings are returned in the order given. A sequence over 1022 residues still runs, but that is the length ESM-2 was trained to attend over and the rest is extrapolated, so the embedding is less reliable and the job says so in its warnings. |
| `labels`          | array   | no       | —       | Optional name for each sequence, one per line, in the same order. Echoed back on the result so you can tell which embedding is which — without it the output is a positional list and FASTA headers are not kept. Give one per sequence or leave it empty; a count that disagrees with the sequences is rejected rather than lined up short. |
| `model_variant`   | string  | no       | `650M`  | Model size to run: "650M" (default, gives a 1280-number vector per protein) or "3B" (larger, gives a 2560-number vector for slightly higher quality at higher cost). One of `650M`, `3B`. |
| `pool`            | string  | no       | —       | How to summarize each protein: "mean" (default, one vector per protein, averaged over residues), "cls" (one vector from the model's summary token), or "none" (a separate vector for every residue, delivered as a downloadable attachment). |
| `return_contacts` | boolean | no       | —       | Also predict a residue-residue contact map for each sequence (how likely each pair of residues is to be in contact). Off by default. |
| `fp16`            | boolean | no       | `true`  | Use faster half-precision math on the GPU (default on). Leave on for speed; it has no meaningful effect on the results. |

#### Example Input

```json
{
  "sequences": [
    "MKIEELKKWVEEFDKKLAEIFKFDFGGYRELADKVAEAVGKKVDEKQKKIVEIFEKVEAEA"
  ],
  "model_variant": "650M",
  "pool": "mean"
}
```

#### Featured Examples

Run one with `azulene examples submit esm2_embed <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID             | Name                                        | Description |
| ---------------------- | ------------------------------------------- | ----------- |
| `esm2-embed-ubiquitin` | Ubiquitin mean-pooled embedding             | Mean-pooled ESM-2 650M embedding for ubiquitin (76 aa) — the canonical fixed-length protein… |
| `esm2-embed-lysozyme`  | Lysozyme CLS embedding + contact map        | CLS-pooled ESM-2 650M embedding plus the unsupervised residue-residue contact map for hen… |
| `esm2-embed-minibatch` | Batched mini-proteins (Trp-cage, HP36, GB1) | One batched call mean-pooling three classic mini-proteins (Trp-cage, villin HP36, GB1) into… |

---

### 31. ESM-2 Zero-Shot Mutation Scoring (`esm2_mutation_score`)

**Description:** Score how point mutations affect a protein, with no training data needed. ESM-2 rates each mutant relative to the wild-type sequence: higher scores mean the model finds the mutation more favorable, lower scores less favorable. Use it to quickly rank or pre-screen candidate mutations.

**Category:** Protein Mutation Scoring · **Docs:** <https://docs.azulenelabs.com/tools/esm2_mutation_score/> · **Submission modes:** `single`

#### Input Schema

| Field           | Type    | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ----------- |
| `sequence`      | string  | yes      | —       | The wild-type protein sequence the mutations are measured against (one-letter amino acids, up to 2048 residues). Past 1022 residues it still runs, but that is ESM-2's trained context and positions beyond it are extrapolated, so scores there are less reliable. |
| `mutants`       | array   | yes      | —       | The point mutations to score, as a list written like "M1A" (original amino acid, 1-based position, new amino acid), up to 4096 of them. Each is checked against the wild-type sequence, so out-of-range positions or a wrong original amino acid are rejected. |
| `model_variant` | string  | no       | `650M`  | Model size to run: "650M" (default) or "3B" (larger, for slightly higher quality at higher cost). One of `650M`, `3B`. |
| `method`        | string  | no       | —       | Scoring method: "masked_marginal" (default, more accurate but slower) or "wt_marginal" (faster but less precise). |
| `fp16`          | boolean | no       | `true`  | Use faster half-precision math on the GPU (default on). Leave on for speed; it has no meaningful effect on the results. |

#### Example Input

```json
{
  "sequence": "MKIEELKKWVEEFDKKLAEIFKFDFGGYRELADKVAEAVGKKVDEKQKKIVEIFEKVEAEA",
  "mutants": [
    "M1A",
    "K2R",
    "I3V"
  ],
  "method": "masked_marginal"
}
```

#### Featured Examples

Run one with `azulene examples submit esm2_mutation_score <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                | Name                                      | Description |
| ------------------------- | ----------------------------------------- | ----------- |
| `esm2-mutation-lysozyme`  | Hen lysozyme catalytic dyad (zero-shot)   | Masked-marginal zero-shot scoring of the hen lysozyme catalytic dyad (Glu35, Asp52) plus a… |
| `esm2-mutation-ubiquitin` | Ubiquitin functional hotspots (zero-shot) | Masked-marginal zero-shot scoring of ubiquitin functional hotspots (Ile44 patch, Lys48/Lys63… |
| `esm2-mutation-gb1`       | GB1 hydrophobic-core alanine scan         | Wild-type-marginal alanine scan over the GB1 hydrophobic core (Y3, L5, F30, W43, F52). |

---

### 32. ESMFold Single-Chain Structure Prediction (`esmfold_predict`)

**Description:** Single-chain structure prediction from sequence with ESMFold — no MSA, up to 1024 residues. Returns per-residue pLDDT and pTM. Coordinates are in the model's own frame with residues numbered from 1, so a centre from another structure will not transfer.

**Category:** Structure Predictions · **Docs:** <https://docs.azulenelabs.com/tools/esmfold_predict/> · **Submission modes:** `single`

#### Input Schema

| Field           | Type    | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ----------- |
| `sequence`      | string  | yes      | —       | The protein sequence to fold (one-letter amino acids, up to 1024 residues). |
| `output_format` | string  | no       | —       | Structure file format to return: "pdb" (default) or "cif" (mmCIF). |
| `chunk_size`    | integer | no       | —       | Advanced memory knob. Smaller values use less GPU memory but run slower; leave unset to use the model default. Lower this only if a long sequence runs out of memory. |
| `num_recycles`  | integer | no       | —       | How many refinement passes the model makes (0 to 8). Default 4. More passes can sharpen the structure; designed or unusual sequences may still score low confidence regardless. |
| `keep_dirs`     | boolean | no       | `true`  | Keep the full prediction outputs so you can download them afterward (recommended). Turn off only if you don't need the raw files. |

#### Example Input

```json
{
  "sequence": "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG",
  "output_format": "pdb",
  "num_recycles": 4
}
```

#### Featured Examples

Run one with `azulene examples submit esmfold_predict <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID            | Name                               | Description |
| --------------------- | ---------------------------------- | ----------- |
| `esmfold-trp-cage`    | Trp-cage TC5b mini-protein (20 aa) | MSA-free ESMFold structure of the Trp-cage TC5b mini-protein (20 aa), PDB output, downloadable. |
| `esmfold-villin-hp36` | Villin headpiece HP36 (mmCIF)      | MSA-free ESMFold structure of the villin headpiece HP36 three-helix bundle (36 aa), mmCIF… |
| `esmfold-ubiquitin`   | Ubiquitin β-grasp fold (76 aa)     | MSA-free ESMFold structure of ubiquitin (76 aa), the textbook beta-grasp fold, PDB output… |

---

### 33. Organic Crystal Structure Prediction (CSP) (`crystal_prediction`)

**Description:** Predict organic crystal structures from a SMILES string or an uploaded molecular geometry. Runs the az_crystals CSP pipeline (CPU orchestrator + GPU fan-out). Provide exactly one of `smiles` or `molecule_filename`. Optionally compare against an experimental CIF.

**Category:** Structure Generation / Sampling · **Docs:** <https://docs.azulenelabs.com/tools/crystal_prediction/> · **Submission modes:** `single`

#### Input Schema

| Field                     | Type    | Required | Default | Description |
| ------------------------- | ------- | -------- | ------- | ----------- |
| `smiles`                  | string  | no       | —       | SMILES string of the molecule. Provide exactly one of smiles or molecule_filename. |
| `molecule_filename`       | file    | no       | —       | Molecular geometry file (.xyz/.cif/.mol/.sdf, any ASE-readable format). Provide exactly one of smiles or molecule_filename. |
| `preset`                  | string  | yes      | `quick` | Search preset: test (tiny/debug), quick (standard), full (exhaustive CSP). One of `test`, `quick`, `full`. |
| `exp_cif_file`            | file    | no       | —       | Optional experimental CIF; predictions are compared to it (energy/density + geometric RMSD match). |
| `exp_is_lowest_polymorph` | boolean | no       | `false` | Assert the experimental structure is the most stable polymorph; report whether the matched prediction is the global energy minimum. |

#### Example Input

```json
{
  "smiles": "CC(=O)Oc1ccccc1C(=O)O",
  "preset": "quick"
}
```

#### Featured Examples

Run one with `azulene examples submit crystal_prediction <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID         | Name                                          | Description |
| ------------------ | --------------------------------------------- | ----------- |
| `aspirin-smiles`   | Aspirin crystal (from SMILES)                 | Predict crystal packings of aspirin (acetylsalicylic acid) from its SMILES string. The… |
| `acetic-acid-xyz`  | Acetic acid crystal (.xyz + experimental CIF) | Predict crystal packings of acetic acid from a relaxed .xyz geometry and compare the predicted… |
| `nicotinamide-sdf` | Nicotinamide crystal (.sdf)                   | Predict crystal packings of nicotinamide (vitamin B3) from a .sdf geometry with explicit… |

---

### Retired job types

Earlier revisions of this document described the ids below. They are not in the live catalog, so submitting one fails before anything runs and no credits are consumed. They are kept here so an old script or notebook has somewhere to land.

| Retired ID             | Why                                                                                                                                                                                                                                                                                                                                         | Use instead |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `mp2`                  | Quantum-chemistry tools were withdrawn from the catalog.                                                                                                                                                                                                                                                                                    | — |
| `hartree_fock`         | Quantum-chemistry tools were withdrawn from the catalog.                                                                                                                                                                                                                                                                                    | — |
| `ccsd_calculation`     | Quantum-chemistry tools were withdrawn from the catalog.                                                                                                                                                                                                                                                                                    | — |
| `xtb_calculation`      | Semi-empirical tool withdrawn from the catalog.                                                                                                                                                                                                                                                                                             | — |
| `molecular_dynamics`   | Plain MD was withdrawn; the free-energy tools run their own MD.                                                                                                                                                                                                                                                                             | `absolute_binding`, `relative_binding` |
| `relative_binding_uaa` | Not in the catalog. The unnatural-amino-acid protocol is only exposed for solvation-phase relative free energies.                                                                                                                                                                                                                           | `relative_fe_uaa` |
| `pocket_docking`       | Commented out of `job_definitions.ts` and never re-enabled, so it is not submittable — and no tool finds a pocket for you: `docking` REQUIRES `binding_site_center`, which you must supply. `pdb_file` is now `structure_file`; `ligand_smiles` keeps its name (`drug_smiles` is a deprecated alias). `chain_id` is newly required on both. | `docking`, `covalent_docking` |
| `upload_file`          | Not a job type. Pass a local path to any `file` field and the SDK uploads it first, then submits the returned storage key.                                                                                                                                                                                                                  | — |
| `predict_admet`        | Temporarily hidden from the public catalog while an ML ADMET water-toxicity result is investigated (SAA-607), not withdrawn. Still registered and runnable internally; it will return here when that is resolved.                                                                                                                           | — |
| `predict_solubility`   | Temporarily hidden from the public catalog while the AqSolDB model is validated (opal-backend #227), not withdrawn. Still registered and submittable by id; it will return here when that is resolved.                                                                                                                                      | — |

---

For live job type info directly on Azulene Studio, always refer to:

```bash
azulene jobs get-job-types
```

or see the [API_Reference.md](API_Reference.md) for usage patterns and CLI/Python examples.



**All Rights Reserved**
<!-- END GENERATED job-types -->
