A CLI and Python library to interact with Azulene Opal

Project description

Azulene-Opal

Opal Quick Start Guide
Opal Job Types

This guide shows how to:

Log in
Submit a job
Inspect and filter jobs
Get / cancel a specific job
Poll running jobs
Check service health & job types
Submit a batch of jobs

Each section has Python and CLI examples.

How to download OPAL CLI

pip install azulene-opal

0. Imports (Python)

from opal import auth, jobs

1. Log in

Python

from opal import auth

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

CLI

# Recommended: let the CLI prompt you (password hidden)
python -m opal.main login
# Your email:    test@example.com
# Your password: *****

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

2. Check who you are

Python

from opal import auth

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

CLI

python -m opal.main whoami

If your account isn’t approved yet, the API will tell you and block job access.

3. Submit a single job

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

Python

from opal 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.)

CLI

python -m opal.main jobs submit \
  --job-type generate_conformers \
  --input-data '{"smiles": "CCO", "num_conformers": 5}'

Each call submits one job.

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

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

CLI

# Last 5 jobs
python -m opal.main jobs get-jobs

# All jobs
python -m opal.main jobs get-jobs --all

# Last 10 jobs
python -m opal.main jobs get-jobs --limit 10

# Filter by job_type + status
python -m opal.main jobs get-jobs \
  --job-type generate_conformers \
  --status completed

# Filter by date range
python -m opal.main jobs get-jobs \
  --start-date 2025-12-01T00:00:00Z \
  --end-date   2025-12-05T00:00:00Z

5. Get a specific job

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

Python

from opal import jobs

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

CLI

python -m opal.main jobs get --job-id YOUR_JOB_ID

6. Cancel a job

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

Python

from opal import jobs

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

CLI

python -m opal.main jobs cancel --job-id YOUR_JOB_ID

7. Poll running jobs

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

Python

from opal import jobs

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

CLI

python -m opal.main jobs check-running-jobs

8. Health check

Check that the Opal backend is reachable.

Python

from opal import jobs

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

CLI

python -m opal.main jobs check-health

9. Discover available job types

List job types supported by the current backend.

Python

from opal import jobs

res = jobs.get_job_types()
print(res)
# {"ok": True, "data": ["generate_conformers", "absolute_solvation_energy_aqueous", ...]}

CLI

python -m opal.main jobs get-job-types

The CLI version prints a prettier, less noisy summary.

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 opal 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",
#                 ...
#             }
#         }
#       },
#       ...
#   ]
# }

CLI

Same thing from the command line, using a JSON list:

python -m opal.main jobs submit-batch-jobs \
  --job-type generate_conformers \
  --input-data '[{"smiles": "CCO", "num_conformers": 5}, {"smiles": "CCCO", "num_conformers": 3}, {"smiles": "CCcndO", "num_conformers": 2}]'

The CLI will print a summary like:

Total jobs
Number of successes / failures
Per-job job_id and status

11. Log out

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

Python

from opal import auth

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

CLI

python -m opal.main logout

TL;DR minimal workflows

Python minimal workflow

from opal 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))

CLI minimal workflow

# 1) Log in
python -m opal.main login

# 2) Submit one job
python -m opal.main jobs submit \
  --job-type generate_conformers \
  --input-data '{"smiles": "CCO", "num_conformers": 5}'

# 3) See your last 5 jobs
python -m opal.main jobs get-jobs

# 4) Get a specific job
python -m opal.main jobs get --job-id YOUR_JOB_ID

Help Commands

python -m opal.main --help

python -m opal.main jobs --help

python -m opal.main jobs submit --help

Opal Quick Start Guide:

This guide walks you through a complete working example of using Opal to submit and monitor an Absolute Binding Free Energy job using a protein and ligand file.

You will learn how to:

a. Install azulene-opal from PyPI
b. Log in via the CLI
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

conda create -n opal-env python=3.11 -y
conda activate opal-env

For Python

# Create a virtual environment
python -m venv opal-env

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

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

a. Install `azulene-opal` from PyPI

pip install azulene-opal

Confirm installation:

python -m opal.main --help

b. Log in using the CLI

Run:

python -m opal.main login

The CLI will securely prompt you:

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

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

c. Place your protein and ligand files

For this example, we place the files in a folder named examples:

examples/
  t4_lysozyme.pdb
  toluene.sdf

The file paths will be:

examples/t4_lysozyme.pdb
examples/toluene.sdf

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

d. Submit an `absolute_binding` job

The job type is:

absolute_binding

The required parameters are:

{
  "pdb_file": "",
  "ligand_sdf_file": ""
}

Example 1: Using the sample files

Using CLI

# Submit an absolute_binding job (CMD)
python -m opal.main jobs submit --job-type absolute_binding --input-data "{\"pdb_file\": \"./examples/data/t4_lysozyme.pdb\", \"ligand_sdf_file\": \"./examples/data/toluene.sdf\"}"

# Submit an absolute_binding job (Git Bash / WSL / Linux / macOS)
python -m opal.main jobs submit --job-type absolute_binding --input-data '{"pdb_file": "./examples/data/t4_lysozyme.pdb", "ligand_sdf_file": "./examples/data/toluene.sdf"}'

# Submit an absolute_binding job (Powershell)
python -m opal.main jobs submit --job-type absolute_binding --input-data '{\"pdb_file\": \"./examples/data/t4_lysozyme.pdb\", \"ligand_sdf_file\": \"./examples/data/toluene.sdf\"}'

Using Python

from opal import jobs

result = jobs.submit(
    job_type="absolute_binding",
    input_data={
        "pdb_file": "./examples/data/t4_lysozyme.pdb",
        "ligand_sdf_file": "./examples/data/toluene.sdf"
    }
)

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 Example

from opal import auth, jobs

# 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": "./examples/data/fkb_model_0_2.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)

CLI Example

python -m opal.main login

Then

python -m opal.main jobs submit \
  --job-type absolute_binding \
  --input-data "{
      \"pdb_file\": \"./examples/data/fkb_model_0_2.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
  }"

Example 3: Using your own files

python -m opal.main jobs submit \
  --job-type absolute_binding \
  --input-data '{"pdb_file": "path/to/your_protein.pdb", "ligand_sdf_file": "path/to/your_ligand.sdf"}'

Replace the paths with your actual file locations.

e. Submit an `Absolute Aqueous Solvation Free Energy` job

The job type is:

aqueous_solvation

The required parameters are:

{
  "smiles": ""
}

Example: Using a simple SMILES (`CCO`)

Using CLI

# Submit an aqueous_solvation job (CMD)
python -m opal.main jobs submit --job-type aqueous_solvation --input-data "{\"smiles\": \"CCO\"}"

# Submit an aqueous_solvation job (Git Bash / WSL / Linux / macOS)
python -m opal.main jobs submit --job-type aqueous_solvation --input-data '{"smiles": "CCO"}'

# Submit an aqueous_solvation job (Powershell)
python -m opal.main jobs submit --job-type aqueous_solvation --input-data '{\"smiles\": \"CCO\"}'

Using Python

from opal import jobs

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

print(result)

You should see something like:

✅ 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):

python -m opal.main jobs get-jobs

All jobs:

python -m opal.main jobs get-jobs --all

Filter by job type and status:

python -m opal.main jobs get-jobs \
  --job-type absolute_binding \
  --status completed

Filter by date:

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

2. Check a specific job

python -m opal.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

python -m opal.main jobs check-running-jobs

Use this to check on running jobs.

4. Cancel a job

python -m opal.main jobs cancel --job-id YOUR_JOB_ID

Only works if the job is still running.

Opal Job Types:

This document lists all currently available Opal job types, their purpose, required inputs, and example payloads.

You can fetch this list via:

python -m opal.main jobs get-job-types

or in Python:

from opal import jobs
jobs.get_job_types()

Overview

ID	Name	Description
`generate_conformers`	Generate Conformers	Generate molecular conformers from SMILES notation
`mp2`	MP2 Calculation	Møller–Plesset second-order perturbation theory
`hartree_fock`	Hartree-Fock Calculation	Self-consistent field Hartree–Fock calculation
`ccsd_calculation`	CCSD Calculation	Coupled Cluster Singles and Doubles
`xtb_calculation`	XTB Calculation	Extended tight-binding semi-empirical calculation
`molecular_dynamics`	Molecular Dynamics	Molecular dynamics simulation
`aqueous_solvation`	Absolute Aqueous Solvation Free Energy	Solvation free energy in water
`relative_fe`	Relative Free Energy	Relative free energy between two molecules in water
`relative_fe_uaa`	Relative Free Energy for (Unnatural) Amino Acids	Relative FE between two (un)natural amino acid structures
`nonaqueous_solvation`	Absolute Nonaqueous Solvation Free Energy	Solvation FE of a solute between two solvents
`reaction_free_energy`	Aqueous Reaction Free Energy	Reaction free energy in aqueous solution
`deprotonation_fe`	Deprotonation Free Energy	Deprotonation free energy in aqueous solution
`absolute_binding`	Absolute Binding Free Energy	Binding FE of a ligand to a protein in water
`relative_binding`	Relative Binding Free Energy	Relative binding FE between two ligands
`relative_binding_uaa`	Relative Binding FE for (Unnatural) Amino Acids	Relative binding FE for (un)natural amino acid ligands
`lipid_permeation`	Lipid Permeation Free Energy	FE of permeation through a lipid bilayer
`pocket_docking`	Pocket Finding and Ligand Docking	Pocket finding + docking of a ligand to a protein
`upload_file`	Upload File	Uploads a file and returns its storage path
`boltz_prediction`	Boltz-2 Affinity and Structure Prediction	Protein–ligand affinity + structure prediction using Boltz-2

1. Generate Conformers (`generate_conformers`)

Description: Generate molecular conformers from SMILES notation.

Input Schema

Field	Type	Required	Default	Description
`smiles`	string	yes	—	SMILES of the molecule
`num_conformers`	number	yes	`5`	Number of conformers to generate

Example Input

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

2. MP2 Calculation (`mp2`)

Description: Møller–Plesset second-order perturbation theory.

Input Schema

Field	Type	Required	Description
`atom`	string	yes	Atomic coordinates in XYZ format
`basis`	string	yes	Basis set for the calculation

Example Input

{
  "atom": "H 0 0 0; H 0 0 0.74",
  "basis": "ccpvdz"
}

3. Hartree-Fock Calculation (`hartree_fock`)

Description: Self-consistent field Hartree–Fock calculation.

Input Schema

Field	Type	Required	Description
`atom`	string	yes	Atomic coordinates in XYZ format
`basis`	string	yes	Basis set for the calculation

Example Input

{
  "atom": "H 0 0 0; F 0 0 1.1",
  "basis": "ccpvdz"
}

4. CCSD Calculation (`ccsd_calculation`)

Description: Coupled Cluster Singles and Doubles calculation.

Input Schema

Field	Type	Required	Description
`atom`	string	yes	Atomic coordinates in XYZ format
`basis`	string	yes	Basis set for the calculation

Example Input

{
  "atom": "H 0 0 0; H 0 0 0.74",
  "basis": "ccpvdz"
}

5. XTB Calculation (`xtb_calculation`)

Description: Extended tight-binding semi-empirical calculation.

Input Schema

Field	Type	Required	Description
`numbers`	array	yes	Atomic numbers of the atoms
`positions`	array	yes	3D coordinates of the atoms

Example Input

{
  "numbers": [8, 1, 1],
  "positions": [
    [0, 0, 0],
    [0.96, 0, 0],
    [-0.24, 0.93, 0]
  ]
}

6. Molecular Dynamics (`molecular_dynamics`)

Description: Molecular dynamics simulation.

Input Schema

Field	Type	Required	Description
`numbers`	array	yes	Atomic numbers
`positions`	array	yes	Initial 3D coordinates

Example Input

{
  "numbers": [1, 1],
  "positions": [
    [0, 0, 0],
    [0.74, 0, 0]
  ]
}

7. Absolute Aqueous Solvation Free Energy (`aqueous_solvation`)

Description: Absolute solvation free energy of a molecule in water via alchemical transformations.

Key Input Fields

Field	Type	Required	Default	Description
`smiles`	string	yes	—	Solute SMILES
`protonate`	boolean	no	`false`	Protonate at given pH
`ph`	number	no	`7`	pH for protonation
`solvent_equil_length`	number	no	`0.08`	Solvent equilibration length (ns / replica)
`solvent_prod_length`	number	no	`0.4`	Solvent production length (ns / replica)
`vacuum_equil_length`	number	no	`0.08`	Vacuum equilibration length (ns / replica)
`vacuum_prod_length`	number	no	`0.4`	Vacuum production length (ns / replica)
`platform`	string	no	`CUDA`	OpenMM platform (`CUDA`, `OpenCL`, `CPU`, `Reference`)
`protocol_repeats`	integer	no	`3`	# of repeats for uncertainty
`keep_dirs`	boolean	no	`True`	Keep working directories

Example Input

{
  "smiles": "CCO"
}

8. Relative Free Energy (`relative_fe`)

Description: Relative FE between two molecules in water.

Key Input Fields

Field	Type	Required	Default	Description
`smiles_a`	string	yes	—	SMILES of molecule A
`smiles_b`	string	yes	—	SMILES of molecule B
`protonate`	boolean	no	`false`	Protonate at pH
`ph`	number	no	`7`	pH value
`equil_length`	number	no	`0.08`	Equilibration length (ns / replica)
`prod_length`	number	no	`0.4`	Production length (ns / replica)
`platform`	string	no	`CUDA`	OpenMM platform
`protocol_repeats`	integer	no	`3`	# of repeats
`keep_dirs`	boolean	no	`True`	Keep working dirs

Example Input

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

9. Relative Free Energy for (Unnatural) Amino Acids (`relative_fe_uaa`)

Description: Relative FE between two (un)natural amino acid sequences.

Key Input Fields

Field	Type	Required	Default	Description
`sequence_a`	string	yes	—	First peptide sequence (standard codes or UAA notation)
`sequence_b`	string	yes	—	Second peptide sequence
`uaa_map`	object	no	—	Map of placeholders (e.g. `{"x": "pF-Phe"}`)
`protonate`	boolean	no	`false`	Protonate at pH
`ph`	number	no	`7`	pH value
`equil_length`	number	no	`0.08`	Equilibration length (ns / replica)
`prod_length`	number	no	`0.4`	Production length (ns / replica)
`platform`	string	no	`CUDA`	OpenMM platform
`protocol_repeats`	integer	no	`3`	# of repeats
`keep_dirs`	boolean	no	`True`	Keep working dirs

Example Input

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

10. Absolute Nonaqueous Solvation Free Energy (`nonaqueous_solvation`)

Description: Solvation FE of a solute between two solvents.

Key Input Fields

Field	Type	Required	Default	Description
`smiles_solute`	string	yes	—	Solute SMILES
`smiles_solvent_a`	string	yes	—	Solvent A SMILES (`"None"` for vacuum)
`smiles_solvent_b`	string	yes	—	Solvent B SMILES (`"None"` for vacuum)
`equil_length`	number	no	`0.08`	Equilibration length (ns / replica)
`prod_length`	number	no	`0.4`	Production length (ns / replica)
`platform`	string	no	`CUDA`	OpenMM platform

Example Input

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

11. Aqueous Reaction Free Energy (`reaction_free_energy`)

Description: Reaction free energy in aqueous solution.

Key Input Fields

Field	Type	Required	Description
`smiles_reactant`	string	yes	Reactants SMILES (comma-separated)
`smiles_product`	string	yes	Products SMILES (comma-separated)
`stoichiometry_reactant`	string	yes	Stoichiometry of reactants (comma-separated)
`stoichiometry_product`	string	yes	Stoichiometry of products (comma-separated)
`solvent_equil_length`	number	no	Solvent equilibration length
`solvent_prod_length`	number	no	Solvent production length
`vacuum_equil_length`	number	no	Vacuum equilibration length
`vacuum_prod_length`	number	no	Vacuum production length
`platform`	string	no	OpenMM platform
`protocol_repeats`	integer	no	# of repeats
`use_xtb`	boolean	no	Use xTB for gas-phase
`keep_dirs`	boolean	no	Keep dirs

Example Input

{
  "smiles_reactant": "C(=O)=O,O",
  "smiles_product": "OC(=O)O",
  "stoichiometry_reactant": "1,1",
  "stoichiometry_product": "1",
  "use_xtb": true
}

12. Deprotonation Free Energy (`deprotonation_fe`)

Description: Deprotonation free energy in aqueous solution.

Key Input Fields

Field	Type	Required	Description
`smiles_prot`	string	yes	SMILES of protonated species
`smiles_deprot`	string	yes	SMILES of deprotonated species
`solvent_equil_length`	number	no	Solvent equilibration
`solvent_prod_length`	number	no	Solvent production
`vacuum_equil_length`	number	no	Vacuum equilibration
`vacuum_prod_length`	number	no	Vacuum production
`platform`	string	no	OpenMM platform
`protocol_repeats`	integer	no	# of repeats
`use_xtb`	boolean	no	Use xTB
`keep_dirs`	boolean	no	Keep dirs

Example Input

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

13. Absolute Binding Free Energy (`absolute_binding`)

Description: Absolute binding FE of a ligand to a protein in water.

Key Input Fields

Field	Type	Required	Description
`pdb_file`	file	yes	Protein PDB (may optionally contain ligand)
`ligand_sdf_file`	file	no	Ligand SDF file
`ligand_pdb_file`	file	no	Ligand PDB file
`ligand_in_pdb_file`	boolean	no	Whether ligand is in protein PDB
`ligand_smiles`	string	no	Ligand SMILES (esp. if ligand is only in PDB)
`solvent_equil_length`	number	no	Ligand solvent equilibration
`solvent_prod_length`	number	no	Ligand solvent production
`complex_equil_length`	number	no	Complex equilibration
`complex_prod_length`	number	no	Complex production
`platform`	string	no	OpenMM platform
`protocol_repeats`	integer	no	# of repeats
`keep_dirs`	boolean	no	Keep dirs

Example Input

{
  "pdb_file": "examples/t4_lysozyme.pdb",
  "ligand_sdf_file": "examples/toluene.sdf"
}

14. Relative Binding Free Energy (`relative_binding`)

Description: Relative binding FE between two ligands to the same protein.

Key Input Fields

Field	Type	Required	Description
`pdb_file`	file	yes	Protein PDB
`ligand_sdf_file_a`	file	no	First ligand SDF
`ligand_sdf_file_b`	file	no	Second ligand SDF
`ligand_pdb_file_a`	file	no	First ligand PDB
`ligand_pdb_file_b`	file	no	Second ligand PDB
`ligand_in_pdb_file_a`	boolean	no	First ligand in protein PDB
`ligand_in_pdb_file_b`	boolean	no	Second ligand in protein PDB
`smiles_a`	string	no	SMILES of ligand A
`smiles_b`	string	no	SMILES of ligand B
`protonate`	boolean	no	Protonate
`ph`	number	no	pH value
`equil_length`	number	no	Equilibration length
`prod_length`	number	no	Production length
`platform`	string	no	OpenMM platform
`protocol_repeats`	integer	no	# of repeats
`keep_dirs`	boolean	no	Keep dirs

Example Input

{
  "pdb_file": "protein.pdb",
  "ligand_sdf_file_a": "ligandA.sdf",
  "ligand_sdf_file_b": "ligandB.sdf"
}

15. Relative Binding FE for (Unnatural) Amino Acids (`relative_binding_uaa`)

Description: Relative binding FE between two (un)natural amino acid ligands.

Key Input Fields

Field	Type	Required	Description
`sequence_a`	string	yes	First peptide sequence
`sequence_b`	string	yes	Second peptide sequence
`pdb_file`	file	yes	PDB file (e.g. from previous job)
`uaa_map`	object	no	Map placeholders to UAA names/SMILES
`protonate`	boolean	no	Protonate
`ph`	number	no	pH value
`equil_length`	number	no	Equilibration
`prod_length`	number	no	Production
`platform`	string	no	OpenMM platform
`protocol_repeats`	integer	no	# of repeats
`keep_dirs`	boolean	no	Keep dirs

Example Input

{
  "sequence_a": "YGH",
  "sequence_b": "xGH",
  "pdb_file": "protein.pdb",
  "uaa_map": "{\"x\": \"pF-Phe\"}"
}

16. Lipid Permeation Free Energy (`lipid_permeation`)

Description: Free energy of a molecule permeating through a lipid bilayer.

Key Input Fields

Field	Type	Required	Description
`smiles`	string	yes	Solute SMILES
`lipid_type`	string	yes	Lipid type (`DPPC`, `DMPC`, `DOPC`, `DLPE`, `DLPC`, `POPE`, `POPC`)
`equil_length`	number	no	Equilibration length
`prod_length`	number	no	Production length
`platform`	string	no	OpenMM platform
`keep_dirs`	boolean	no	Keep dirs

Example Input

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

17. Pocket Finding and Ligand Docking (`pocket_docking`)

Description: Find the binding pocket and dock a ligand to a protein.

Key Input Fields

Field	Type	Required	Description
`pdb_file`	file	yes	Protein PDB
`ligand_smiles`	string	yes	Ligand SMILES
`ph`	float	no	pH value (default: 7)

Example Input

{
  "pdb_file": "protein.pdb",
  "ligand_smiles": "CC1=CC=CC=C1"
}

18. Upload File (`upload_file`)

Description: Uploads a file and returns its storage path.

Input Schema

Field	Type	Required	Description
`file_path`	file	yes	Local file path to upload

Example Input

{
  "file_path": "examples/input.txt"
}

19. Boltz-2 Affinity and Structure Prediction (`boltz_prediction`)

Description: Boltz-2 based affinity and structure prediction.

Input Schema

Field	Type	Required	Description
`protein_sequence`	string	yes	Protein sequence (one-letter amino acid code)
`ligand_smiles`	string	yes	Ligand SMILES

Example Input

{
  "protein_sequence": "MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPSLNAAK",
  "ligand_smiles": "CC1=CC=CC=C1"
}

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

python -m opal.main jobs get-job-types

or see the API_Reference.md for usage patterns and CLI/Python examples.

Project details

Release history Release notifications | RSS feed

0.4.11

Jun 26, 2026

0.4.10

Jun 23, 2026

0.4.9

May 5, 2026

0.4.8

May 5, 2026

0.4.7

Mar 5, 2026

0.4.6

Mar 5, 2026

0.4.5

Mar 5, 2026

0.4.4

Mar 5, 2026

0.4.3

Dec 11, 2025

This version

0.4.2

Dec 10, 2025

0.4.1

Dec 10, 2025

0.4.0

Dec 10, 2025

0.3.0

Nov 5, 2025

0.2.0

Aug 4, 2025

0.1.0

Aug 2, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

azulene_opal-0.4.2.tar.gz (33.7 kB view details)

Uploaded Dec 10, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

azulene_opal-0.4.2-py3-none-any.whl (18.8 kB view details)

Uploaded Dec 10, 2025 Python 3

File details

Details for the file azulene_opal-0.4.2.tar.gz.

File metadata

Download URL: azulene_opal-0.4.2.tar.gz
Upload date: Dec 10, 2025
Size: 33.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.0

File hashes

Hashes for azulene_opal-0.4.2.tar.gz
Algorithm	Hash digest
SHA256	`ba42e9dee6fe8a2922d87b2cc6e34434860a1b5fcbf3575a3663924ba94d89f6`
MD5	`e6367cd73e08a81fc67230f1931e54c6`
BLAKE2b-256	`66408e6b5abcd31dae1170921c2532f20a6cba22722b19d1618e81101b84e61c`

See more details on using hashes here.

File details

Details for the file azulene_opal-0.4.2-py3-none-any.whl.

File metadata

Download URL: azulene_opal-0.4.2-py3-none-any.whl
Upload date: Dec 10, 2025
Size: 18.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.0

File hashes

Hashes for azulene_opal-0.4.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`2c8cb3ad5c8f58fb464998b3291cb4ce583c8731bd03c34395643760c959f018`
MD5	`c205545185d9e329a6cf93f91d6ceeaa`
BLAKE2b-256	`78b2727e7c787ded14478fa7cdd877846f9f237824708b6fce954c76a60322aa`

See more details on using hashes here.

azulene-opal 0.4.2

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Project description

Azulene-Opal

How to download OPAL CLI

0. Imports (Python)

1. Log in

Python

CLI

2. Check who you are

Python

CLI

3. Submit a single job

Python

CLI

4. List and filter jobs

Python

CLI

5. Get a specific job

Python

CLI

6. Cancel a job

Python

CLI

7. Poll running jobs

Python

CLI

8. Health check

Python

CLI

9. Discover available job types

Python

CLI

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

Python

CLI

11. Log out

Python

CLI

TL;DR minimal workflows

Python minimal workflow

CLI minimal workflow

Help Commands

Opal Quick Start Guide:

Create and activate a virtual environment (optional)

For conda

For Python

a. Install azulene-opal from PyPI

b. Log in using the CLI

c. Place your protein and ligand files

d. Submit an absolute_binding job

Example 1: Using the sample files

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

Example 3: Using your own files

e. Submit an Absolute Aqueous Solvation Free Energy job

Example: Using a simple SMILES (CCO)

f. Other useful commands

1. List your jobs

2. Check a specific job

3. Poll running jobs

4. Cancel a job

Opal Job Types:

Overview

1. Generate Conformers (generate_conformers)

Input Schema

Example Input

2. MP2 Calculation (mp2)

Input Schema

Example Input

3. Hartree-Fock Calculation (hartree_fock)

Input Schema

Example Input

4. CCSD Calculation (ccsd_calculation)

Input Schema

Example Input

a. Install `azulene-opal` from PyPI

d. Submit an `absolute_binding` job

e. Submit an `Absolute Aqueous Solvation Free Energy` job

Example: Using a simple SMILES (`CCO`)

1. Generate Conformers (`generate_conformers`)

2. MP2 Calculation (`mp2`)

3. Hartree-Fock Calculation (`hartree_fock`)

4. CCSD Calculation (`ccsd_calculation`)

5. XTB Calculation (`xtb_calculation`)

6. Molecular Dynamics (`molecular_dynamics`)

7. Absolute Aqueous Solvation Free Energy (`aqueous_solvation`)

8. Relative Free Energy (`relative_fe`)

9. Relative Free Energy for (Unnatural) Amino Acids (`relative_fe_uaa`)

10. Absolute Nonaqueous Solvation Free Energy (`nonaqueous_solvation`)

11. Aqueous Reaction Free Energy (`reaction_free_energy`)

12. Deprotonation Free Energy (`deprotonation_fe`)

13. Absolute Binding Free Energy (`absolute_binding`)

14. Relative Binding Free Energy (`relative_binding`)

15. Relative Binding FE for (Unnatural) Amino Acids (`relative_binding_uaa`)

16. Lipid Permeation Free Energy (`lipid_permeation`)

17. Pocket Finding and Ligand Docking (`pocket_docking`)

18. Upload File (`upload_file`)

19. Boltz-2 Affinity and Structure Prediction (`boltz_prediction`)