OPAL ML Optimize

OPAL ML Optimize takes a protein with a ligand sitting in its pocket and tidies up the geometry, meaning it nudges the atoms into a lower energy, more realistic arrangement. It does this using the OPAL machine learning potential, a neural network model that predicts the energy and forces of a molecular system far faster than a full quantum calculation while staying close to that level of accuracy.

A docked pose, which is one position of the ligand in the pocket, often has small clashes or slightly off geometry left over from the docking step. This tool relaxes those out. The point of the run is to produce clean, optimised structures so that the next step, scoring, gives a reliable binding energy.

When to use it

Use it as the step between docking and scoring. After Docking or Covalent Docking gives you poses, run this to relax the geometry, then pass the result to OPAL ML Score for the binding energy. You can start from a ZIP of docked poses, or from a separate protein file and ligand file (or a ligand that is already inside the protein, named by its residue name).

Inputs

You provide the structure either as a ZIP of poses from a docking run, or as a protein file together with a ligand. All inputs are optional in the schema, but you must give one of those two starting points.

Input	Required	What it is
`poses_file`	no	A ZIP of `.traj` pose files from a Covalent Docking run.
`protein_file`	no	A protein structure in PDB or CIF format. Use this instead of `poses_file`.
`ligand_file`	no	A ligand structure in SDF format, already positioned in the protein frame.
`ligand_resname`	no	The residue name of the ligand if it is already inside the protein PDB.
`chain_id`	no	Which protein chain to use.
`protein_charge`	no, default `0`	The formal charge of the protein fragment.
`ligand_charge`	no, default `0`	The formal charge of the ligand. Worked out from the SDF when left at `0`.
`opt_fmax`	no, default `0.05`	Force convergence threshold in eV per Angstrom. The optimiser stops once the largest force on any atom drops below this. Smaller values relax more tightly.
`opt_maxiter`	no, default `200`	Largest number of optimisation steps.
`top_k`	no, default `5`	When starting from `poses_file`, how many of the top poses to optimise. Allowed range `1` to `20`.
`keep_cofactors`	no	JSON list of cofactor residue names to keep, for example `["ZN", "HEM"]`.
`extra_chains`	no	JSON list of extra protein chain IDs to include, for example `["B"]`.

How to run it

Submit your structures from Azulene Studio, the Python SDK, or the CLI. New here? The Get started page walks through installing, logging in, and running a ready made example first.

In Azulene Studio

Open OPAL ML Optimize from the tools list, then on the Inputs and Parameters step provide your input. Either upload the ZIP of poses from a docking run, or upload a protein file plus a ligand file (or name the ligand already inside the protein with its residue name and chain). Adjust the optimisation settings if you want, then Review and Submit.

From the Python SDK

from opal import jobs

result = jobs.submit(
    job_type="opal_ml_optimize",
    input_data={
        "protein_file": "/path/to/your/protein.pdb",
        "ligand_resname": "N3",
        "chain_id": "A",
    },
)

From the CLI

Pass the inputs as a JSON string.

opal jobs submit --job-type opal_ml_optimize \
  --input-data '{"protein_file": "/path/to/your/protein.pdb", "ligand_resname": "N3", "chain_id": "A"}'

Reading the result

The headline numbers are the number of poses optimised (n_poses_optimized) and the wall time in seconds (computation_time), the total time the run took.

The real output of this tool is the set of optimised structures, which the next step consumes. Feed the result straight into OPAL ML Score to turn these relaxed geometries into a binding energy. (For protein to protein inputs, the result may also carry a per pose table with charge and atom count details; for the ordinary protein and ligand case that table is empty and only the two headline numbers show.)

Notes

This tool relaxes geometry only, it does not give you a binding energy on its own, so always follow it with OPAL ML Score. Relaxing more tightly (a smaller opt_fmax) gives a cleaner geometry but takes longer. If your ligand carries a charge and you are not starting from an SDF, set ligand_charge so the energies are computed correctly. Keep any structural cofactors with keep_cofactors so the pocket stays realistic.