Metadata-Version: 2.4
Name: azulene-studio
Version: 0.5.13
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 Score Pose / Optimize Pose](#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` 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 (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 Aqueous Solvation 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": "Generate Conformers", ...}, ...]}}
```


---

## 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 Score Pose / Optimize Pose

`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: **Score Pose** (`opal_ml_score`) and
**Optimize Pose** (`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. |
| `ligand_file`   | `supplied`             | An SDF or MOL, which is what a **Peptide Structure** (HELM to 3D) run hands over — pass its `structure_sdf_url`. Multi-record files are conformers of one molecule and the first record is read. Charges are taken as written. |
| `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`. |

`ligand_file` is **not** a starting conformer, and cannot be made into one:
the folder builds its own conformer for a ligand and rejects a non-protein
chain from its template machinery. It changes *what* is folded, never where the
fold starts. The one risk it carries is a stale or edited file — the peptide
fold uses `binder.sequence` whatever the file says, so a mismatched file gives
you an affinity for one molecule and an interaction energy for another, both
individually valid. The job compares the two on the heavy-atom skeleton (a
protonation difference is not flagged; a different molecule is) and puts a
warning in `warnings`.

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.

<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-08-23 (35 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. `absolute_binding` takes
`pdb_file` and `ligand_smiles`; `docking` takes `structure_file` and
`drug_smiles`. 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 Pose Prediction                   | Structure Prediction            | Predict ternary PROTAC linker poses (target + E3 ligase) via rigid-body prescan, GPU… |
| `generate_conformers`          | Generate Conformers                              | Structure Generation / Sampling | Generate molecular conformers from SMILES notation |
| `aqueous_solvation`            | Absolute Aqueous Solvation Free Energy           | Molecular Property Prediction   | Calculates the absolute solvation free energy of a molecule (SMILES) or peptide (HELM) in… |
| `predict_protein_properties`   | Protein & Peptide Property Profiler              | Property Prediction             | Predict key developability properties of a protein or peptide directly from its sequence… |
| `relative_fe`                  | Relative Free Energy                             | Binding Free Energy             | Calculates the relative free energy between two similar molecules in water using alchemical… |
| `relative_fe_uaa`              | Relative Free Energy for (Unnatural) Amino Acids | Binding Free Energy             | 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 Nonaqueous Solvation Free Energy        | 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                        | Molecular Property Prediction   | Calculates the deprotonation free energy in aqueous solution (pKa proxy). Accepts SMILES or… |
| `absolute_binding`             | Absolute Binding Free Energy                     | Binding Free Energy             | Calculates the absolute binding free energy of a ligand to a protein in aqueous solution. |
| `relative_binding`             | Relative Binding Free Energy                     | Binding Free Energy             | Calculates the relative binding free energy between two ligands to a protein in aqueous… |
| `lipid_permeation`             | Lipid 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 Permeation Free Energy            | Molecular Property Prediction   | Calculates the relative free energy of permeation through a lipid bilayer between two… |
| `predict_solubility`           | Aqueous Solubility ML Prediction                 | Property Prediction             | Predict aqueous solubility (logS) of a molecule from its SMILES string using an XGBoost model… |
| `predict_admet`                | ADMET ML Prediction                              | Property Prediction             | Predict a multi-endpoint ADMET profile with traffic-light triage, MPO scoring, and… |
| `covalent_docking`             | Covalent Docking                                 | Structure-Based Drug Design     | Covalent docking into a target residue you name — the platform has no pocket finding… |
| `docking`                      | Docking                                          | Structure-Based Drug Design     | Docking into a binding site you supply — the platform has no pocket finding and will not… |
| `sequential_docking`           | Sequential Docking                               | Structure-Based Drug Design     | Multi-stage docking where every non-covalent stage needs its own binding site centre — the… |
| `opal_ml_optimize`             | Optimize Pose                                    | Structure-Based Drug Design     | LBFGS-relax the ligand or binder inside the frozen receptor with the OPAL ML neural potential… |
| `opal_ml_score`                | Score Pose                                       | Structure-Based Drug Design     | Compute protein-ligand interaction energy using OPAL ML single-point energies. Fast scoring on… |
| `peptide_structure`            | Peptide 3D Structure from HELM                   | Structure Generation            | Generate 3D structures from HELM notation for linear and cyclic peptides, including… |
| `protein_mutation_ddg_fold`    | Protein Mutation ΔΔG Fold                        | 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… |
| `boltz_ppi`                    | Boltz-2 Protein-Protein Binding Surfaces         | Structure Predictions           | Predict the K most favorable protein-protein binding surfaces (default K=5) from two protein… |
| `boltz_macrocycle`             | Macrocycle & Cyclic-Peptide affinity scoring     | Structure Predictions           | Predict how a macrocyclic or stapled peptide binds a protein receptor. **The binder is a…** |
| `chai_prediction`              | Chai-1 Structure Prediction                      | Structure Predictions           | All-atom co-folding with Chai-1 (Apache-2.0). Supports protein, RNA, DNA, and small-molecule… |
| `openfold3_prediction`         | OpenFold3 Structure Prediction                   | Structure Predictions           | AF3-parity all-atom structure prediction with OpenFold3 (Apache-2.0). Within experimental… |
| `openfold2_prediction`         | OpenFold2 Structure Prediction                   | Structure Predictions           | Single-chain and multimer protein structure prediction with OpenFold2 (Apache-2.0). OpenFold2… |
| `mpnn_design`                  | MPNN 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 (ΔΔG)            | Structure Predictions           | Predict how mutations change a protein's folding stability (ΔΔG, in kcal/mol) from its… |
| `esm2_embed`                   | ESM-2 Sequence Embeddings                        | Protein Embeddings              | Turn protein sequences into ESM-2 embeddings — numeric vectors that capture each protein's… |
| `esm2_mutation_score`          | ESM-2 Mutation Scoring (Zero-Shot)               | Protein Mutation Scoring        | Score how point mutations affect a protein, with no training data needed. ESM-2 rates each… |
| `esmfold_predict`              | ESMFold — Fast Single-Chain Structure Prediction | Structure Predictions           | Predict the 3D structure of a single protein chain straight from its sequence, with no MSA… |
| `crystal_prediction`           | Crystal Structure Prediction                     | Structure Generation / Sampling | Predict organic crystal structures from a SMILES string or an uploaded molecular geometry… |

---

### 1. PROTAC Ternary 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 Prediction · **Submission modes:** `single`

#### Input Schema

| Field                       | Type    | Required | Default  | Description |
| --------------------------- | ------- | -------- | -------- | ----------- |
| `job_id`                    | string  | no       | —        | Caller-supplied job id (used for the per-job working dir on the shared volume). |
| `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 SMILES fragment with attachment points ([*:1]…[*:2]) connecting warhead and recruiter. |
| `warhead_attach_atom_idx`   | integer | yes      | —        | Warhead attachment atom index (0-based). |
| `recruiter_attach_atom_idx` | integer | yes      | —        | E3-recruiter attachment atom index (0-based). |
| `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": "OCCOCCOCC",
  "warhead_attach_atom_idx": 0,
  "recruiter_attach_atom_idx": 0,
  "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     | Fast coarse-grid demo on the best-resolved VHL system (degrader MS67, RCSB 7JTP). |
| `6sis-brd4-vhl-quick`   | BRD4-VHL (6SIS) - quick     | Fast coarse-grid demo (macroPROTAC-1, RCSB 6SIS). |
| `7jtp-wdr5-vhl`         | WDR5-VHL (7JTP) - medium    | Production-reference run; the blind top-1 pick lands ~2.0 A from the 7JTP crystal pose… |
| `6sis-brd4-vhl`         | BRD4-VHL (6SIS) - medium    | Production-reference run; a sub-3 A pose sits in the top-5 (macroPROTAC-1, RCSB 6SIS). |
| `8g1q-smarca2-vhl`      | SMARCA2-VHL (8G1Q) - medium | Production-reference run on SMARCA2 (cmpd_3603, RCSB 8G1Q). |
| `8g1q-smarca2-vhl-long` | SMARCA2-VHL (8G1Q) - long   | Long preset (theta_max=110 deg) recovers 8G1Q's high-theta E3 pose that the medium grid's… |

---

### 2. Generate Conformers (`generate_conformers`)

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

**Category:** Structure Generation / Sampling · **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 Aqueous Solvation 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 · **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/reference/helm/ |
| `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 & Peptide Property Profiler (`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 · **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/reference/helm/ |
| `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 Free Energy (`relative_fe`)

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

**Category:** Binding Free Energy · **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 Free Energy for (Unnatural) Amino Acids (`relative_fe_uaa`)

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

**Category:** Binding Free Energy · **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 · **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/reference/helm/ |
| `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 Nonaqueous Solvation Free Energy (`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 · **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/reference/helm/ |
| `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 · **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 (`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 · **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/reference/helm/ |
| `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/reference/helm/ |
| `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 (`absolute_binding`)

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

**Category:** Binding Free Energy · **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 in the PDB file (only needed when extracting ligand from cocrystal PDB, auto-detected if omitted) |
| `ligand_residue_name`       | string  | no       | —       | Residue name of the ligand in the PDB file (only needed when extracting ligand from cocrystal PDB, auto-detected if omitted) |
| `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 (`relative_binding`)

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

**Category:** Binding Free Energy · **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 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 · **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/reference/helm/ |
| `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 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 · **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. Aqueous Solubility ML Prediction (`predict_solubility`)

**Description:** Predict aqueous solubility (logS) of a molecule from its SMILES string using an XGBoost model trained on AqSolDB

**Category:** Property Prediction · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field    | Type   | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------- |
| `smiles` | string | yes      | —       | SMILES notation of the molecule |

#### Example Input

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

#### Featured Examples

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

| Example ID             | Name                 | Description |
| ---------------------- | -------------------- | ----------- |
| `caffeine-solubility`  | Caffeine solubility  | Predict the aqueous solubility (logS) of caffeine, a small, highly soluble stimulant. |
| `aspirin-solubility`   | Aspirin solubility   | Predict the aqueous solubility (logS) of aspirin (acetylsalicylic acid), a moderately soluble… |
| `ibuprofen-solubility` | Ibuprofen solubility | Predict the aqueous solubility (logS) of ibuprofen, a lipophilic, poorly soluble drug. |

---

### 16. ADMET ML Prediction (`predict_admet`)

**Description:** Predict a multi-endpoint ADMET profile with traffic-light triage, MPO scoring, and advance/optimize/drop bucketing from a SMILES string.

**Category:** Property Prediction · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field       | Type   | Required | Default | Description |
| ----------- | ------ | -------- | ------- | ----------- |
| `smiles`    | string | yes      | —       | SMILES notation of the molecule |
| `endpoints` | array  | no       | `[]`    | Optional subset of ADMET endpoints to predict. Leave empty to run the full profile. Items are any of `caco2`, `hia`, `pgp`, `bioavailability`, `solubility`, `lipophilicity`, `bbb`, `ppbr`, `vdss`, `cyp2c9`, `cyp2d6`, `cyp3a4`, `cyp2c9_sub`, `cyp2d6_sub`, `cyp3a4_sub`, `half_life`, `cl_hepatocyte`, `cl_microsome`, `herg`, `ames`, `ld50`, `dili`. |

#### Example Input

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

#### Featured Examples

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

| Example ID               | Name                   | Description |
| ------------------------ | ---------------------- | ----------- |
| `caffeine-admet`         | Caffeine ADMET         | Run the full ADMET profile on caffeine, a small well-behaved molecule, for a quick… |
| `imatinib-admet`         | Imatinib ADMET         | Run the full ADMET profile on imatinib, a larger marketed kinase-inhibitor drug, to show the… |
| `sulfamethoxazole-admet` | Sulfamethoxazole ADMET | Run the full ADMET profile on sulfamethoxazole, a sulfonamide antibiotic, to show a different… |

---

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

**Description:** Covalent docking into a target residue you name — the platform has no pocket finding. target_resname, target_resid and target_atom are all required: you must already know which residue the warhead attacks. Physics-based, supporting boronic acids, acrylamides, nitriles, sulfonyl fluorides and other warhead classes. Three-stage scoring: pose generation, classical rescoring, and composite ranking.

**Category:** Structure-Based Drug Design · **Submission modes:** `single`

#### Input Schema

| Field                | Type    | Required | Default    | Description |
| -------------------- | ------- | -------- | ---------- | ----------- |
| `structure_file`     | file    | yes      | —          | Protein structure file (PDB or CIF format) |
| `drug_smiles`        | string  | yes      | —          | SMILES string of the covalent inhibitor (must contain a reactive warhead) |
| `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. Use :1 atom map to mark the reactive atom. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. The warhead is detected from built-in SMARTS patterns and cannot be overridden. |
| `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. |
| `n_conformers`       | integer | no       | `1`        | Number of ligand conformers to sample. Higher values improve results for flexible ligands but increase runtime. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 1–10. |
| `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 from the receptor (e.g. 'ZN' or 'ZN,NDP'). Leave empty to strip every non-standard residue. Names are PDB chemical-component IDs; no spaces after the commas. Waters are REMOVED when the pocket is cropped - add HOH to keep them, but that keeps every water in the structure, not a chosen one. Metal ions carry their formal charge into scoring; organic cofactors (NADPH, ATP, FAD...) are retained with correct protonation but scored as NEUTRAL, so absolute dG for an anionic cofactor is offset while ranking within one receptor is unaffected. CA is calcium, not the C-alpha atom. |
| `extra_chains`       | string  | no       | —          | Comma-separated additional chain IDs to include (e.g. 'B' or 'B,C'). |
| `optimize_and_score` | boolean | no       | `false`    | Run end-to-end: after covalent docking, automatically chain GPU-accelerated geometry optimization (opal_ml_optimize) and ML scoring (opal_ml_score). Results are returned as the final ML-scoring envelope with structures and scores ranked for binding-affinity inspection. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. |
| `opt_fmax`           | number  | no       | `0.05`     | Convergence force threshold (eV/Å) for GPU optimization. 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 forward into GPU optimization + scoring. 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. |

#### Example Input

```json
{
  "structure_file": "<local path or storage key>",
  "drug_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… |

---

### 18. Docking (`docking`)

**Description:** Docking into a binding site you supply — the platform has no pocket finding and will not locate one for you. Non-covalent docking of small molecules, fragments or cofactors; binding_site_center is required. The centre is in Angstroms in the uploaded structure's OWN coordinate frame — a centre taken from a reference crystal, or from a predicted model (which uses its own arbitrary frame and numbers residues from 1), does not carry over, so derive it from the file you are uploading. A centre with no protein atom within 8 A of it is rejected at submission rather than docked into bulk solvent. If you do not know where the ligand binds, boltz_prediction co-folds protein and ligand from sequence and needs no pocket at all; it is not a substitute for physics-based docking, but it is the only route when the site is unknown.

**Category:** Structure-Based Drug Design · **Submission modes:** `single`, `batch`, `workflow_node`

#### Input Schema

| Field                   | Type    | Required | Default | Description |
| ----------------------- | ------- | -------- | ------- | ----------- |
| `structure_file`        | file    | yes      | —       | Protein structure file (PDB or CIF format) |
| `drug_smiles`           | string  | no       | —       | SMILES string of the ligand or cofactor to dock. Provide this OR 'helm'. |
| `helm`                  | string  | no       | —       | Cyclic or linear peptide in HELM2 notation, e.g. PEPTIDE1{A.G.F.K.L}$$$$V2.0 — provide this OR 'drug_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/reference/helm/ |
| `ligand_file`           | file    | no       | —       | Ligand as a file (SDF, MOL, MOL2 or PDB) — provide this OR 'drug_smiles' OR 'helm'. Only the molecule is taken from it, not its coordinates: docking builds its own conformer ensemble in the pocket, and for a macrocycle it regenerates the ring conformers regardless. A multi-record SDF docks the first record only. This is the field to use for a structure produced by 'peptide_structure', which returns one directly as 'structure_sdf_url'; results from before 2026-08-19 carry it inside 'results_file' as structure.sdf instead. 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 cyclic-peptide/macrocycle sampling arm. 'auto' (default) turns it on when the ligand has a flexible ring larger than 8 atoms — which is what you want, and what an ordinary small molecule never triggers. The arm uses ETKDGv3 macrocycle torsions, a larger conformer pool, and seeds the generative samples across several distinct ring conformers, because a macrocycle's ring pucker is otherwise frozen at the input seed. It is markedly slower than small-molecule docking. 'off' forces the small-molecule settings even for a macrocycle. 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. Has NO effect when binding_site_center is set, which is required - it neither steers the docking nor changes the reported pose-to-pocket distance, which is measured from the center. Use it to derive a center: the wizard averages these residues' atoms and fills binding_site_center in. Numbers are as written in the uploaded file (author numbering, not a 1-based index). The match ignores chain, so a number present in several chains averages over all of them; insertion codes cannot be addressed - a residue number matches EVERY residue with that number regardless of insertion code, which matters for Kabat/Chothia-numbered antibodies (H100, H100A...). For an Fv, renumber to IMGT or set binding_site_center directly. |
| `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_conformers`          | integer | no       | `3`     | Number of ligand 3D conformers to generate. NOT CURRENTLY IMPLEMENTED — this value is accepted and then ignored; it has no effect on the result. Range 1–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 from the receptor (e.g. 'ZN' or 'ZN,NDP'). Leave empty to strip every non-standard residue. Names are PDB chemical-component IDs; no spaces after the commas. Waters are REMOVED when the pocket is cropped - add HOH to keep them, but that keeps every water in the structure, not a chosen one. Metal ions carry their formal charge into scoring; organic cofactors (NADPH, ATP, FAD...) are retained with correct protonation but scored as NEUTRAL, so absolute dG for an anionic cofactor is offset while ranking within one receptor is unaffected. CA is calcium, not the C-alpha atom. |
| `fmax`                  | number  | no       | `0.5`   | LBFGS 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. |

##### `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>",
  "drug_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-benzene`                 | Benzene → T4 lysozyme L99A cavity                   | Non-covalent docking of benzene into the engineered hydrophobic cavity of T4 lysozyme L99A… |
| `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-cyclised 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 cyclised 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… |

---

### 19. Sequential Docking (`sequential_docking`)

**Description:** Multi-stage docking where every non-covalent stage needs its own binding site centre — the platform will not find one for you. Dock cofactors, fragments or ligands one at a time; each stage uses the previous result as the frozen receptor for the next, and covalent and non-covalent stages can be mixed. A covalent stage derives its centre from anchor_atom_name instead; a non-covalent stage with neither is rejected at submission, because it would otherwise be skipped and contribute nothing to the result. As with docking, centres are in Angstroms in the uploaded structure's own frame.

**Category:** Structure-Based Drug Design · **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 from the receptor (e.g. 'ZN' or 'ZN,NDP'). Leave empty to strip every non-standard residue. Names are PDB chemical-component IDs; no spaces after the commas. Waters are REMOVED when the pocket is cropped - add HOH to keep them, but that keeps every water in the structure, not a chosen one. Metal ions carry their formal charge into scoring; organic cofactors (NADPH, ATP, FAD...) are retained with correct protonation but scored as NEUTRAL, so absolute dG for an anionic cofactor is offset while ranking within one receptor is unaffected. CA is calcium, not the C-alpha atom. |

##### `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… |

---

### 20. Optimize Pose (`opal_ml_optimize`)

**Description:** LBFGS-relax the ligand or binder inside the frozen receptor with the OPAL ML neural potential, then score the relaxed geometry and return the usual scoring envelope. `opt_fmax` and `opt_maxiter` control the relaxation. The relaxed complex is published as `relaxed_complex_file`, and a fresh `opal_ml_inputs` block points at it so this job can be chained into Score Pose — which is the point: scoring the pose you started from would report a post-relaxation number computed before the relaxation. If the relaxation fails for a pose, that pose is scored exactly as supplied and the result says so. Peptide, macrocycle and stapled-peptide binders are supported: name the binder chain in `binder_chain`, which switches the job to the peptide-complex path and makes `ligand_smiles` unnecessary — a peptide binder has no SMILES. **On that peptide path the relaxation is newly enabled and changes the runtime:** it previously failed and degraded silently to "not relaxed", returning in about a minute; a real relaxation of a macrocycle complex has been measured at 6-7 minutes. Check `pose_relaxed_in_pocket` on the result — it is the per-job answer to whether the relaxation actually ran, and it is more reliable than this description. **Flexible target residues.** By default the whole receptor is held rigid and only the binder moves. Set `flexible_radius` (or name residues with `flexible_residues`) to let pocket side chains relax with it — a macrocycle or peptide on a shallow protein-protein surface binds partly by side-chain accommodation, which a rigid pocket cannot represent. The default of 0 keeps the previous behaviour exactly. Read `receptor_shift_a`, `n_flexible_residues` and `flexible_residues_resolved` on the result to see what moved, and note that an induced-fit dG is systematically more negative than a rigid-pocket one and the two must not be compared. **Macrocycle and non-canonical binders.** A binder whose residues have no AMBER parameters — a macrocycle of non-canonical amino acids, a stapled peptide, or a single-residue ligand from a docking hand-off — is perceived as a MOLECULE instead: bond orders and pH 7.4 protonation come from `ligand_smiles`, and partial charges from the ligand force field. Supply `ligand_smiles` for those, or chain from the job that published it in its `opal_ml_inputs` block; without it the job refuses rather than scoring the binder with no electrostatics. `binder_route` on the result says which path ran.

**Category:** Structure-Based Drug Design · **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 this empty: the structure contains the molecule, and bond orders, protonation and charges are read from it — by RDKit's residue templates for a named peptide chain (what boltz_macrocycle and an RFpeptides design after ProteinMPNN emit), or from geometry plus the pose's own hydrogens for a single-residue ligand (what a docking hand-off publishes). Set it only when the perceived molecule is wrong, or when the pose is a bare heavy-atom skeleton with no residue names for a template to match. The result reports which route was used. A SMILES whose atom formula disagrees with the structure is refused rather than applied. |
| `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/reference/helm/ |
| `drug_smiles`         | string  | no       | —       | SMILES for the binder, a synonym of 'ligand_smiles' so a chain from Docking can forward the field under the name that job uses. Supply at most one of 'ligand_smiles', 'helm' and 'drug_smiles'. |
| `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** inside the same structure — the thing being scored, as opposed to `chain_id`, which names the receptor. Supplying it switches the job to the peptide-complex path: the complex is split by chain, each side is protonated separately, and the receptor is cropped to the pocket. Use it for peptide, macrocycle and stapled-peptide binders; leave it unset for small molecules. **Passing a peptide binder as `chain_id` instead does not raise an error** — the job takes the small-molecule path, which perceives the ligand with RDKit, cannot represent a polymer, and returns an interaction energy that is not meaningful. |
| `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 along with it, instead of holding the whole target rigid. **0 (the default) keeps every receptor atom frozen, which is what this job has always done** — turn it on deliberately. A macrocycle or peptide on a shallow protein-protein surface binds partly BY side-chain accommodation, and a rigid pocket cannot represent that. 4 is a sensible pocket shell. Only side chains move: the backbone stays frozen unless you also set `flexible_backbone`, so this is a rotamer rearrangement, not a refold. **The resulting dG is not comparable with a rigid-pocket run.** It is an induced-fit interaction energy: the receptor's own strain cancels between the complex and the protein reference, but the cost of leaving its unbound conformation is not charged for, so the number comes out systematically more negative. Check `receptor_shift_a` and `flexible_residues_resolved` on the result to see how far the pocket actually moved and which residues did it. Range 0–12. |
| `flexible_residues`   | string  | no       | —       | Name the receptor residues to relax explicitly, as `CHAIN:RESSEQ` — for example `A:145,A:41`. Takes precedence over `flexible_radius` when both are given. Use the residue NUMBER, not its name: protonation relabels histidines to HID/HIE/HIP before the relaxation runs. A residue that is not in the receptor being scored (wrong chain, or cropped away with the rest of the protein) is reported in the warnings and stays frozen; if NONE of them match, the job fails and tells you which chains and residue ranges are actually present. The same caveat as `flexible_radius` applies to the number that comes back. |
| `flexible_backbone`   | boolean | no       | `false` | Also let the backbone of the flexible residues move (N, CA, C, O and their hydrogens), instead of side chains only. Off by default and worth leaving off: freezing the backbone is what keeps the relaxation a side-chain rearrangement rather than a slow unfolding of the pocket crop. Turn it on for a loop you expect to reorganise on binding. Has no effect unless `flexible_radius` or `flexible_residues` selected something. |
| `crop_radius`         | number  | no       | `10`    | For a PEPTIDE binder (`binder_chain` set): keep only receptor residues within this many Angstrom of the binder. 0 disables cropping. This is not an optimization — the interaction energy is a difference of two whole-receptor energies, and on a large receptor that difference is swamped by absolute-energy noise, which destroys ranking. Cropping is applied only above `crop_min_atoms` receptor atoms, because a fixed radius over-crops a small receptor and makes it worse. Ignored on the small-molecule path, which truncates around the ligand instead. Range 0–30. |
| `interior_dielectric` | number  | no       | `1`     | Solute interior dielectric for the MM-GBSA correction on the PEPTIDE-binder path. 1 is the value the reported composite was benchmarked at, and it is the VACUUM-INTERIOR extreme of the defensible range — it maximises the desolvation penalty, which matters most for a charged binder. **The sign of the composite is not robust to this choice.** Measured on a cyclic-peptide/PD-L1 complex whose binder carries net +2: at eps_in=1 the MM-GBSA term is +286 and the composite is +21 (positive, i.e. reads as non-binding); at eps_in=2 it is +141 and the composite -124; at 4, +69 and -198. The term scales as 1/eps to within 1%, which is textbook Born behaviour rather than anything numerically wrong, and `dg_nnp` is flat across all three because the neural potential does not see this parameter. eps_in of 2-4 is the conventional range when charged groups are buried. Nothing here says which value is right — that is a modelling judgement, and 1 is defensible for a rigid-receptor single-structure protocol — but read the composite with the parameter in view, and prefer `opal_ml_dg_nnp_kcal_mol` if you want a number this knob does not move. Ignored on the small-molecule path. Range 1–20. |
| `keep_cofactors`      | string  | no       | —       | Comma-separated cofactor residue names to retain from the receptor (e.g. 'ZN' or 'ZN,NDP'). Leave empty to strip every non-standard residue. Names are PDB chemical-component IDs; no spaces after the commas. Waters are REMOVED when the pocket is cropped - add HOH to keep them, but that keeps every water in the structure, not a chosen one. Metal ions carry their formal charge into scoring; organic cofactors (NADPH, ATP, FAD...) are retained with correct protonation but scored as NEUTRAL, so absolute dG for an anionic cofactor is offset while ranking within one receptor is unaffected. CA is calcium, not the C-alpha atom. |
| `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)… |

---

### 21. Score Pose (`opal_ml_score`)

**Description:** Compute protein-ligand interaction energy using OPAL ML single-point energies. Fast scoring on pre-optimized or raw structures. Peptide, macrocycle and stapled-peptide binders are supported as well: name the binder chain in `binder_chain` and the complex is scored by the peptide path — split by chain, protonated per side, receptor cropped to the pocket — instead of the small-molecule path, which cannot represent a polymer.

**Category:** Structure-Based Drug Design · **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** inside the same structure — the thing being scored, as opposed to `chain_id`, which names the receptor. Supplying it switches the job to the peptide-complex path: the complex is split by chain, each side is protonated separately, and the receptor is cropped to the pocket. Use it for peptide, macrocycle and stapled-peptide binders; leave it unset for small molecules. **Passing a peptide binder as `chain_id` instead does not raise an error** — the job takes the small-molecule path, which perceives the ligand with RDKit, cannot represent a polymer, and returns an interaction energy that is not meaningful. |
| `ligand_smiles`       | string | no       | —       | OVERRIDE for the binder's chemistry. Normally leave this empty: the structure contains the molecule, and bond orders, protonation and charges are read from it — by RDKit's residue templates for a named peptide chain (what boltz_macrocycle and an RFpeptides design after ProteinMPNN emit), or from geometry plus the pose's own hydrogens for a single-residue ligand (what a docking hand-off publishes). Set it only when the perceived molecule is wrong, or when the pose is a bare heavy-atom skeleton with no residue names for a template to match. The result reports which route was used. A SMILES whose atom formula disagrees with the structure is refused rather than applied. |
| `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/reference/helm/ |
| `drug_smiles`         | string | no       | —       | SMILES for the binder, a synonym of 'ligand_smiles' so a chain from Docking can forward the field under the name that job uses. Supply at most one of 'ligand_smiles', 'helm' and 'drug_smiles'. |
| `crop_radius`         | number | no       | `10`    | For a PEPTIDE binder (`binder_chain` set): keep only receptor residues within this many Angstrom of the binder. 0 disables cropping. This is not an optimization — the interaction energy is a difference of two whole-receptor energies, and on a large receptor that difference is swamped by absolute-energy noise, which destroys ranking. Cropping is applied only above `crop_min_atoms` receptor atoms, because a fixed radius over-crops a small receptor and makes it worse. Ignored on the small-molecule path, which truncates around the ligand instead. Range 0–30. |
| `interior_dielectric` | number | no       | `1`     | Solute interior dielectric for the MM-GBSA correction on the PEPTIDE-binder path. 1 is the value the reported composite was benchmarked at, and it is the VACUUM-INTERIOR extreme of the defensible range — it maximises the desolvation penalty, which matters most for a charged binder. **The sign of the composite is not robust to this choice.** Measured on a cyclic-peptide/PD-L1 complex whose binder carries net +2: at eps_in=1 the MM-GBSA term is +286 and the composite is +21 (positive, i.e. reads as non-binding); at eps_in=2 it is +141 and the composite -124; at 4, +69 and -198. The term scales as 1/eps to within 1%, which is textbook Born behaviour rather than anything numerically wrong, and `dg_nnp` is flat across all three because the neural potential does not see this parameter. eps_in of 2-4 is the conventional range when charged groups are buried. Nothing here says which value is right — that is a modelling judgement, and 1 is defensible for a rigid-receptor single-structure protocol — but read the composite with the parameter in view, and prefer `opal_ml_dg_nnp_kcal_mol` if you want a number this knob does not move. Ignored on the small-molecule path. Range 1–20. |
| `keep_cofactors`      | string | no       | —       | Comma-separated cofactor residue names to retain from the receptor (e.g. 'ZN' or 'ZN,NDP'). Leave empty to strip every non-standard residue. Names are PDB chemical-component IDs; no spaces after the commas. Waters are REMOVED when the pocket is cropped - add HOH to keep them, but that keeps every water in the structure, not a chosen one. Metal ions carry their formal charge into scoring; organic cofactors (NADPH, ATP, FAD...) are retained with correct protonation but scored as NEUTRAL, so absolute dG for an anionic cofactor is offset while ranking within one receptor is unaffected. CA is calcium, not the C-alpha atom. |
| `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… |

---

### 22. Peptide 3D Structure from 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 · **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/reference/helm/ |
| `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… |

---

### 23. Protein Mutation ΔΔG Fold (`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 · **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/reference/helm/ |
| `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… |

---

### 24. 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 · **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… |

---

### 25. Boltz-2 Protein-Protein Binding Surfaces (`boltz_ppi`)

**Description:** Predict the K most favorable protein-protein binding surfaces (default K=5) from two protein sequences using Boltz-2. Returns diverse representative interfaces (default 5), ranked by interface confidence, with per-residue interface lists. Combined chain length capped at 1500 residues.

**Category:** Structure Predictions · **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 add GPU time 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       | —       | Boltz 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 boltz_ppi <example-id>`, or fetch its inputs first with `azulene examples download`.

| Example ID                  | Name                                | Description |
| --------------------------- | ----------------------------------- | ----------- |
| `boltz-ppi-barnase-barstar` | Barnase-Barstar interface           | Boltz-2 protein-protein binding-surface prediction for the classic barnase-barstar complex. |
| `boltz-ppi-pd1-pdl1`        | PD-1 / PD-L1 immune checkpoint      | Boltz-2 protein-protein binding-surface prediction for the PD-1 / PD-L1 immune checkpoint (PDB… |
| `boltz-ppi-kras-raf1-rbd`   | KRAS / RAF1-RBD oncogenic interface | Boltz-2 protein-protein binding-surface prediction for the oncogenic RAS-effector interaction… |

---

### 26. Macrocycle & Cyclic-Peptide affinity scoring (`boltz_macrocycle`)

**Description:** Predict how a macrocyclic or stapled peptide binds a protein receptor. **The binder is a peptide chain, not a ligand SMILES** — you give its one-letter sequence and declare non-standard residues (`modifications`) and crosslinks (`bonds`) on top of it. There is now a `ligand_smiles` field and it does NOT change that: it names the chemistry of a second, additional fold, and it cannot stand in for the sequence. That sequence plus its modifications and bonds already names every atom, so the same binder is co-folded a second time as a molecule, from a SMILES assembled out of the very same component definitions — `ligand_arm` turns that off, `ligand_smiles` or `helm` say where its chemistry comes from instead. Returns the best-scoring diverse poses (default 5), ranked by interface confidence. Poses are sampled under steric and geometry steering potentials, so the diffusion actively avoids atom clashes and distorted bond geometry. Combined receptor+binder length is capped at 1500 residues. Also returns an **experimental** binding-affinity estimate `affinity_pkd` (higher = tighter): use it to separate strong binders from weak ones, not to rank close analogs of one another. Returned poses are also scored with an OPAL-ML interaction energy (`opal_ml_dg_nnp_kcal_mol`, kcal/mol) — a machine-learned-potential interaction energy, not a calibrated binding free energy. Its implicit-solvent counterpart (`opal_ml_dg_mmgbsa_kcal_mol`) and the sum of the two (`opal_ml_dg_kcal_mol`) are returned alongside it. It is reported only where the binder's chemistry allows: a binder carrying non-canonical residues that have no protonation template, hydrocarbon staples among them, reports no energy rather than an unreliable one. The affinity estimate and the interface scores are unaffected either way. Every result is also packaged for hand-off: `opal_ml_inputs` carries the receptor and the pose set in the form the **Score Pose** and **Optimize Pose** tools take, so a macrocycle run can be fed straight into either one without re-uploading anything. That block comes from the ligand fold whenever it ran — `from_arm` says which — because both tools take a ligand, and a chemistry that was an INPUT is not one that had to be read back out of the coordinates. `opal_ml_inputs_by_arm` carries both folds' hand-offs if you would rather score the peptide complex the affinity describes. Coming the other way, a **Peptide Structure** (HELM to 3D) result pipes in here: pass its `smiles` as `ligand_smiles`, or the HELM itself as `helm`, and the ligand fold uses that chemistry instead of assembling its own.

**Category:** Structure Predictions · **Submission modes:** `single`

#### Input Schema

| Field                 | Type    | Required | Default | Description |
| --------------------- | ------- | -------- | ------- | ----------- |
| `receptor`            | object  | yes      | —       | Target protein chain — JSON **object** (single chain, not an array). Minimal value: `{"sequence": "<one-letter AA string>"}`. `id` defaults to `"A"`, `msa.mode` defaults to `"server"`. **Trim the receptor to the binding domain.** Pasting a full-length UniProt sequence is the biggest quality lever on this tool and it fails quietly: a full-length receptor folds far worse than a domain-scoped one on the same target, and the interface you are scoring degrades with it. All three featured examples ship domain slices for that reason. |
| `binder`              | object  | yes      | —       | Macrocyclic / stapled peptide binder — JSON **object**, expressed as a peptide CHAIN, not a ligand SMILES. Minimal value: `{"sequence": "<one-letter AA string>"}`. `id` defaults to `"B"`. Non-standard residues go in `modifications`; the crosslink itself goes in `bonds`. The binder MSA is always empty (a designed macrocycle has no homologues to align). |
| `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, as `[{kind, atom1: {residue, atom}, atom2: {residue, atom}}]`. Residue indices are 1-based into `binder.sequence`. This is where staples, disulfides, lactams and thioethers go — they are side-chain bridges on a linear backbone, so they belong here and NOT in `binder.cyclic`. Leave `atom` empty and the canonical crosslink atom for that `kind` is used (SG for disulfide, CZ/CJ for the S5/R8 staple olefins). |
| `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, with no affinity head. The peptide fold above is unchanged and still produces the binding affinity, the crosslink report and the poses shown in the viewer. This second fold exists for what comes AFTER prediction: Score Pose and Optimize Pose take a ligand, so a peptide pose has to be re-perceived as a molecule from its own coordinates — and that is where the chain breaks. On a stapled peptide, perception returned an amide as a hemiaminal and a hydrocarbon staple as a bicyclobutane, from a pose whose two staple carbons sat 0.49 A apart. A ring declared in a molecular graph cannot fail to close. Turning this off returns the single-fold result and roughly halves the runtime. |
| `ligand_file`         | file    | no       | —       | The binder as a 3D molecule file (SDF or MOL), read for its CHEMISTRY. This is what a **Peptide Structure** (HELM to 3D) result hands over — pass its `structure_sdf_url` here and the ligand fold uses that molecule instead of assembling one from the sequence. Multi-record files are fine: the records are conformers of one molecule and the first is read. It is NOT a starting conformer — the folder builds its own for a SMILES ligand and offers no way to supply one — so this changes what is folded, never where it starts. Checked against what `binder.sequence`, `modifications` and `bonds` describe, and you get a warning if they are 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` using the same PDB Chemical Component Dictionary entries the peptide fold uses, which is exact for every CCD code. Supply it to override that, for instance to state a protonation state of your own: a SMILES you write 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/reference/helm/ |
| `runtime`             | object  | no       | —       | Runtime knobs. `{use_msa_server: bool=true, use_potentials: bool=true, no_kernels: bool=false}`. `use_potentials` steers the diffusion with VDW-overlap, geometry and ring-closure potentials, so poses come out clash-free and covalently sane; it is on by default and costs roughly 3x the sampling time. Set it false only if you need the fastest possible run and will filter poses yourself. Structures are always returned as PDB. |
| `templates`           | array   | no       | —       | Structural templates for the BINDER chain, as `[{"url": <PDB or CIF file>, "chain_id": "B", "force": true, "threshold": 1.5}]`. Use this when you already know the binder's bound conformation — a co-crystal, an NMR model, or a close homolog. **Set `force` to true or the template does nothing**: without it the structure only conditions the network weakly, and on a confident complex that moves the result by about 0.01 Å. With `force`, supplying the deposited conformation improved binder accuracy from 1.36 to 1.01 Å on our PD-L1 example. The same lever applied to a computationally generated conformer made it worse (1.36 → 3.38 Å), so template a structure you trust, not one you guessed. PDB and CIF only — never SDF. `chain_id` must name the binder: templating the receptor would replace the structure you asked to dock against. |
| `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… |

---

### 27. Chai-1 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 · **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… |

---

### 28. OpenFold3 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 · **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… |

---

### 29. OpenFold2 Structure Prediction (`openfold2_prediction`)

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

**Category:** Structure Predictions · **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… |

---

### 30. MPNN 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 · **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… |

---

### 31. ThermoMPNN — Mutation Stability (ΔΔ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 · **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. |

---

### 32. ESM-2 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 · **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… |

---

### 33. ESM-2 Mutation Scoring (Zero-Shot) (`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 · **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). |

---

### 34. ESMFold — Fast Single-Chain Structure Prediction (`esmfold_predict`)

**Description:** Predict the 3D structure of a single protein chain straight from its sequence, with no MSA required. Residues are numbered from 1, not from wherever your construct begins - but you do not have to correct that yourself: if you give a downstream job pocket residues or a covalent target residue in your reference numbering, submission renumbers them into this model's frame and tells you it did, provided the residue names make the shift unambiguous. Coordinates are a different matter: they are in the model's own arbitrary frame, so a binding_site_center taken from a reference crystal is meaningless against it and has to be recomputed from this model. ESMFold is fast and a good fit when you have just a sequence and want a quick fold, including for designed or unusual proteins. Returns the structure plus per-residue confidence (pLDDT) and an overall pTM score. Sequences can be up to 1024 residues.

**Category:** Structure Predictions · **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… |

---

### 35. Crystal Structure Prediction (`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 · **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. `pdb_file` is now `structure_file` and `ligand_smiles` is now `drug_smiles`; `chain_id` and `binding_site_center` are required. | `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.                                                                                                                                | — |

---

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