Dock API#

Configuration #

class Box(center, size)#

Bases: object

Docking box specification storing center and box size.

Parameters:

center (Tuple[float, float, float]) – Center coordinates of the docking box as (x, y, z).
size (Tuple[float, float, float]) – Box dimensions along each axis as (sx, sy, sz).

center: Tuple[float, float, float]#

size: Tuple[float, float, float]#

classmethod from_mapping(value)#

Construct a Box from a flexible mapping or pair representation.

Accepted inputs are:

an existing Box instance,
a dictionary with "center" and "size",
a two-item list or tuple of the form [center, size].

Parameters:

value (Union[Box, Dict[str, Any], List[Any], Tuple[Any, Any]]) – Source object describing a docking box.

Returns:

Parsed docking box instance.

Return type:

Box

Raises:

TypeError – If the input is not a supported box representation.
ValueError – If either center or size is missing, or if either vector is not a valid 3-vector.

Example#

box = Box.from_mapping(
    {
        "center": [1.0, 2.0, 3.0],
        "size": [20.0, 20.0, 20.0],
    }
)

to_dict()#

Convert the box to a JSON-serializable dictionary.

Returns:: Dictionary with "center" and "size" keys stored as lists.
Return type:: Dict[str, List[float]]

Example#

payload = Box(
    center=(1.0, 2.0, 3.0),
    size=(20.0, 20.0, 20.0),
).to_dict()

class SingleConfig( engine='vina', receptor=None, ligand=None, box=None, autobox_ref=None, autobox_pad=None, exhaustiveness=None, n_poses=None, cpu=None, seed=None, out=None, log=None, executable=None, engine_options=<factory>, validate_receptor=False, )#

Bases: object

Configuration for a single docking task.

This compact form stores all parameters needed to launch one receptor-ligand docking job.

Parameters:

engine (str) – Docking engine name, for example "vina".
receptor (Optional[str]) – Receptor input file path.
ligand (Optional[str]) – Ligand input file path.
box (Optional[Box]) – Explicit docking box definition.
autobox_ref (Optional[str]) – Reference ligand or structure used for autoboxing.
autobox_pad (Optional[float]) – Padding added around the autobox reference.
exhaustiveness (Optional[int]) – Docking exhaustiveness parameter.
n_poses (Optional[int]) – Number of poses to generate.
cpu (Optional[int]) – Number of CPU cores to use.
seed (Optional[int]) – Random seed for reproducible runs.
out (Optional[str]) – Output pose file path.
log (Optional[str]) – Log file path.
executable (Optional[str]) – Explicit executable path for the engine binary.
engine_options (Dict[str, Any]) – Extra engine-specific keyword options.
validate_receptor (bool) – Whether to validate receptor format/content before docking.

engine: str = 'vina'#

receptor: str | None = None#

ligand: str | None = None#

box: Box | None = None#

autobox_ref: str | None = None#

autobox_pad: float | None = None#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

out: str | None = None#

log: str | None = None#

executable: str | None = None#

engine_options: Dict[str, Any]#

validate_receptor: bool = False#

classmethod from_dict(data)#

Build a SingleConfig from a mapping.

If a "box" entry is present, it is normalized through Box.from_mapping().

Parameters:: data (Dict[str, Any]) – Input configuration mapping.
Returns:: Parsed single-task configuration.
Return type:: SingleConfig

Example#

cfg = SingleConfig.from_dict(
    {
        "engine": "vina",
        "receptor": "protein.pdbqt",
        "ligand": "ligand.pdbqt",
        "box": {
            "center": [1.0, 2.0, 3.0],
            "size": [20.0, 20.0, 20.0],
        },
    }
)

classmethod from_file(path)#

Load a SingleConfig from a JSON or YAML file.

Parameters:

path (JsonPath) – Configuration file path.

Returns:

Parsed single-task configuration.

Return type:

SingleConfig

Raises:

FileNotFoundError – If the file does not exist.
RuntimeError – If a YAML file is provided but PyYAML is unavailable.
TypeError – If the file root is not a mapping.

Example#

cfg = SingleConfig.from_file("config.json")

to_dict()#

Convert the configuration into a serializable dictionary.

Returns:: Dictionary representation suitable for JSON or YAML output.
Return type:: Dict[str, Any]

Example#

payload = cfg.to_dict()

class LigandSpec( id: 'str', ligand: 'str', out: 'Optional[str]' = None, log: 'Optional[str]' = None, exhaustiveness: 'Optional[int]' = None, n_poses: 'Optional[int]' = None, cpu: 'Optional[int]' = None, seed: 'Optional[int]' = None, engine_options: 'Dict[str, Any]'=<factory>, retries: 'Optional[int]' = None, metadata: 'Dict[str, Any]'=<factory>, )#

Bases: object

Parameters:

id (str)
ligand (str)
out (str | None)
log (str | None)
exhaustiveness (int | None)
n_poses (int | None)
cpu (int | None)
seed (int | None)
engine_options (Dict[str, Any])
retries (int | None)
metadata (Dict[str, Any])

id: str#

ligand: str#

out: str | None = None#

log: str | None = None#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

engine_options: Dict[str, Any]#

retries: int | None = None#

metadata: Dict[str, Any]#

classmethod from_dict(data)#

Build a LigandSpec from a mapping.

The method supports a few convenience aliases:

if "id" is missing, it is inferred from the ligand filename stem,
if "ligand" is missing but "path" is present, "path" is used as the ligand path.

Parameters:: data (Dict[str, Any]) – Ligand configuration mapping.
Returns:: Parsed ligand specification.
Return type:: LigandSpec

Example#

lig = LigandSpec.from_dict(
    {
        "path": "inputs/erlotinib.pdbqt",
        "seed": 42,
    }
)

to_dict()#

Convert the ligand specification into a serializable dictionary.

Returns:: Dictionary representation of the ligand specification.
Return type:: Dict[str, Any]

class SoftwareSpec( name, executable=None, exhaustiveness=None, n_poses=None, cpu=None, seed=None, out_dir=None, log_dir=None, engine_options=<factory>, ligands=<factory>, )#

Bases: object

Per-engine specification nested under a receptor entry.

Parameters:

name (str) – Engine name, for example "vina" or "qvina".
executable (Optional[str]) – Optional explicit executable path.
exhaustiveness (Optional[int]) – Default exhaustiveness for ligands under this software block.
n_poses (Optional[int]) – Default number of poses for ligands under this software block.
cpu (Optional[int]) – Default CPU count for ligands under this software block.
seed (Optional[int]) – Default random seed for ligands under this software block.
out_dir (Optional[str]) – Output directory for generated docking poses.
log_dir (Optional[str]) – Directory for engine log files.
engine_options (Dict[str, Any]) – Additional engine-specific options.
ligands (List[LigandSpec]) – Ligand specifications associated with this engine block.

name: str#

executable: str | None = None#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

out_dir: str | None = None#

log_dir: str | None = None#

engine_options: Dict[str, Any]#

ligands: List[LigandSpec]#

classmethod from_dict(data)#

Build a SoftwareSpec from a mapping.

Any entries in "ligands" are normalized into LigandSpec instances.

Parameters:: data (Dict[str, Any]) – Software configuration mapping.
Returns:: Parsed software specification.
Return type:: SoftwareSpec

Example#

sw = SoftwareSpec.from_dict(
    {
        "name": "vina",
        "ligands": [
            {"id": "lig1", "ligand": "lig1.pdbqt"},
        ],
    }
)

to_dict()#

Convert the software specification into a serializable dictionary.

Returns:: Dictionary form with serialized ligand blocks.
Return type:: Dict[str, Any]

class ReceptorSpec( id: 'str', receptor: 'str', box: 'Optional[Box]' = None, out_dir: 'Optional[str]' = None, log_dir: 'Optional[str]' = None, autobox_ref: 'Optional[str]' = None, autobox_pad: 'Optional[float]' = None, validate_receptor: 'bool' = False, softwares: 'List[SoftwareSpec]' = <factory>, metadata: 'Dict[str, Any]'=<factory>, )#

Bases: object

Parameters:

id (str)
receptor (str)
box (Box | None)
out_dir (str | None)
log_dir (str | None)
autobox_ref (str | None)
autobox_pad (float | None)
validate_receptor (bool)
softwares (List[SoftwareSpec])
metadata (Dict[str, Any])

id: str#

receptor: str#

box: Box | None = None#

out_dir: str | None = None#

log_dir: str | None = None#

autobox_ref: str | None = None#

autobox_pad: float | None = None#

validate_receptor: bool = False#

softwares: List[SoftwareSpec]#

metadata: Dict[str, Any]#

classmethod from_dict(data)#

Build a ReceptorSpec from a mapping.

Supported conveniences:

if "id" is absent, it is inferred from the receptor file stem,
if "receptor" is absent but "path" exists, "path" is used,
"engines" is accepted as an alias for "softwares",
"box" is normalized through Box.from_mapping().

Parameters:: data (Dict[str, Any]) – Receptor configuration mapping.
Returns:: Parsed receptor specification.
Return type:: ReceptorSpec

Example#

receptor = ReceptorSpec.from_dict(
    {
        "path": "receptors/4WKQ.pdbqt",
        "box": {
            "center": [1.0, 2.0, 3.0],
            "size": [20.0, 20.0, 20.0],
        },
        "engines": [
            {"name": "vina", "ligands": []},
        ],
    }
)

to_dict()#

Convert the receptor specification into a serializable dictionary.

Returns:: Dictionary form with serialized software blocks and box.
Return type:: Dict[str, Any]

class DockRow( id, receptor, ligand, box=None, center=None, size=None, autobox_ref=None, autobox_pad=None, out=None, log=None, exhaustiveness=None, n_poses=None, cpu=None, seed=None, engine_options=<factory>, retries=None, )#

Bases: object

Backward-compatible flat docking row representation.

This structure is useful for legacy batch layouts where each row already combines receptor, ligand, and per-task engine parameters.

Parameters:

id (str) – Row or task identifier.
receptor (str) – Receptor input file path.
ligand (str) – Ligand input file path.
box (Optional[Box]) – Optional pre-built box object.
center (Optional[Tuple[float, float, float]]) – Optional center triple used together with size.
size (Optional[Tuple[float, float, float]]) – Optional size triple used together with center.
autobox_ref (Optional[str]) – Optional autobox reference.
autobox_pad (Optional[float]) – Optional autobox padding.
out (Optional[str]) – Optional output file path.
log (Optional[str]) – Optional log file path.
exhaustiveness (Optional[int]) – Docking exhaustiveness.
n_poses (Optional[int]) – Number of poses to generate.
cpu (Optional[int]) – CPU count.
seed (Optional[int]) – Random seed.
engine_options (Dict[str, Any]) – Extra engine-specific options.
retries (Optional[int]) – Retry count for the row.

id: str#

receptor: str#

ligand: str#

box: Box | None = None#

center: Tuple[float, float, float] | None = None#

size: Tuple[float, float, float] | None = None#

autobox_ref: str | None = None#

autobox_pad: float | None = None#

out: str | None = None#

log: str | None = None#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

engine_options: Dict[str, Any]#

retries: int | None = None#

classmethod from_dict(data)#

Build a DockRow from a mapping.

The method normalizes:

"box" via Box.from_mapping(),
"center" and "size" via _tuplize3().

Parameters:: data (Dict[str, Any]) – Flat row configuration mapping.
Returns:: Parsed flat row instance.
Return type:: DockRow

Example#

row = DockRow.from_dict(
    {
        "id": "job1",
        "receptor": "protein.pdbqt",
        "ligand": "ligand.pdbqt",
        "center": [1, 2, 3],
        "size": [20, 20, 20],
    }
)

resolved_box()#

Resolve the effective docking box for the row.

Resolution follows this order:

return self.box when already set,
construct a new Box from center and size when both are available,
otherwise return None.

Returns:: Resolved docking box or None if insufficient information exists.
Return type:: Optional[Box]

Example#

box = row.resolved_box()

to_dict()#

Convert the flat row into a serializable dictionary.

If a box can be resolved, a serialized "box" entry is included.

Returns:: Dictionary representation of the docking row.
Return type:: Dict[str, Any]

class BatchConfig( engine=None, n_jobs=1, progress=True, default_retries=1, timeout=None, tmp_root=None, out_dir=None, log_dir=None, engine_options=<factory>, exhaustiveness=None, n_poses=None, cpu=None, seed=None, autobox_ref_key=None, autobox_pad=None, retries=None, rows=<factory>, receptors=<factory>, )#

Bases: object

Batch configuration supporting both flat and receptor-centric layouts.

Parameters:

engine (str | None)
n_jobs (int)
progress (bool)
default_retries (int)
timeout (float | None)
tmp_root (str | None)
out_dir (str | None)
log_dir (str | None)
engine_options (Dict[str, Any])
exhaustiveness (int | None)
n_poses (int | None)
cpu (int | None)
seed (int | None)
autobox_ref_key (str | None)
autobox_pad (float | None)
retries (int | None)
rows (List[DockRow])
receptors (List[ReceptorSpec])

engine: str | None = None#

n_jobs: int = 1#

progress: bool = True#

default_retries: int = 1#

timeout: float | None = None#

tmp_root: str | None = None#

out_dir: str | None = None#

log_dir: str | None = None#

engine_options: Dict[str, Any]#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

autobox_ref_key: str | None = None#

autobox_pad: float | None = None#

retries: int | None = None#

rows: List[DockRow]#

receptors: List[ReceptorSpec]#

classmethod from_dict(data)#

Build a BatchConfig from a mapping.

Supported aliases:

"ligands" is accepted as an alias for "rows",
"receptors" contains receptor-centric blocks.

Parameters:: data (Dict[str, Any]) – Batch configuration mapping.
Returns:: Parsed batch configuration.
Return type:: BatchConfig

Example#

batch = BatchConfig.from_dict(
    {
        "engine": "vina",
        "rows": [
            {
                "id": "job1",
                "receptor": "protein.pdbqt",
                "ligand": "ligand.pdbqt",
            }
        ],
    }
)

classmethod from_file(path)#

Load a BatchConfig from a JSON or YAML file.

Parameters:

path (JsonPath) – Configuration file path.

Returns:

Parsed batch configuration.

Return type:

BatchConfig

Raises:

FileNotFoundError – If the file does not exist.
RuntimeError – If a YAML file is requested without PyYAML installed.
TypeError – If the configuration root is not a mapping.

Example#

batch = BatchConfig.from_file("batch.json")

to_dict()#

Convert the batch configuration into a serializable dictionary.

Returns:: Dictionary representation of the full batch configuration.
Return type:: Dict[str, Any]

CampaignConfig#: alias of BatchConfig

LigandTask#: alias of LigandSpec

Registry #

register(name, factory)#

The registry stores backend factories using the lowercase form of name. Re-registering the same name replaces the previous factory.

Parameters:

name (str) – Human-readable backend name, such as "vina" or "smina". Registration is case-insensitive.
factory (Callable[[], Any]) – Zero-argument callable returning a backend instance or other engine-specific object.

Returns:

None.

Return type:

None

Example#

class VinaBackend:
    pass

register("vina", lambda: VinaBackend())

factory(name)#

Return the registered factory for a backend name.

Lookup is case-insensitive. If the backend name is not present in the registry, a KeyError is raised with a message listing the currently available engine keys.

Parameters:: name (str) – Backend name to resolve.
Raises:: KeyError – If no backend factory is registered under name.
Returns:: The registered zero-argument backend factory.
Return type:: Callable[[], Any]

Example#

fac = factory("vina")
backend = fac()

available()#

Return the sorted list of registered backend keys.

The returned keys are the canonical lowercase names stored in the internal registry.

Returns:: Sorted list of registered engine names.
Return type:: List[str]

Example#

names = available()
print(names)

register_many(items)#

Each item in items must be a (name, factory) pair. Registration is delegated to register(), so names remain case-insensitive and later entries overwrite earlier ones with the same normalized key.

Parameters:: items (Iterable[tuple[str, Callable[[], Any]]]) – Iterable of (name, factory) pairs to register.
Returns:: None.
Return type:: None

Example#

register_many([
    ("vina", lambda: VinaBackend()),
    ("smina", lambda: SminaBackend()),
])

Single docking #

class SingleResult(artifacts)#

Bases: object

Result wrapper for a single docking execution.

Parameters:: artifacts (RunArtifacts) – Collected run artifacts including output path, log path, executed command, and backend metadata.

artifacts: RunArtifacts#

class SingleDock(engine='vina')#

Bases: object

Facade for one receptor-ligand-engine docking run.

This class provides a fluent interface around a registered docking backend. It can be configured manually through chained setter calls or initialized from a SingleConfig object, mapping, or configuration file.

Parameters:: engine (str) – Docking engine key registered in the backend registry.
Raises:: KeyError – If no backend factory is registered for the requested engine.

Example#

result = (
    SingleDock("qvina")
    .set_receptor("protein.pdbqt", validate=True)
    .set_ligand("ligand.pdbqt")
    .set_box((1.0, 2.0, 3.0), (20.0, 20.0, 20.0))
    .set_out("dock_out.pdbqt")
    .set_log("dock.log")
    .run()
)

set_receptor(path, *, validate=False)#

Set the receptor structure for the docking backend.

Parameters:

path (PathLike) – Receptor input file path.
validate (bool) – Whether receptor validation should be performed by the backend.

Returns:

The current instance for fluent chaining.

Return type:

SingleDock

Example#

dock = SingleDock("qvina").set_receptor("protein.pdbqt", validate=True)

set_ligand(path)#

Set the ligand structure for the docking backend.

Parameters:: path (PathLike) – Ligand input file path.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

Example#

dock = SingleDock("qvina").set_ligand("ligand.pdbqt")

set_box(center, size)#

Set an explicit docking box.

Parameters:

center (Vec3) – Box center coordinates as (x, y, z).
size (Vec3) – Box dimensions as (sx, sy, sz).

Returns:

The current instance for fluent chaining.

Return type:

SingleDock

Example#

dock = SingleDock("qvina").set_box(
    (1.0, 2.0, 3.0),
    (20.0, 20.0, 20.0),
)

enable_autobox(reference_file, padding=None)#

Enable autoboxing using a reference structure or ligand.

Parameters:

reference_file (PathLike) – Path to the structure used as the autobox reference.
padding (Optional[float]) – Optional padding added around the automatically inferred box.

Returns:

The current instance for fluent chaining.

Return type:

SingleDock

Example#

dock = SingleDock("vina").enable_autobox("ref_ligand.pdbqt", padding=4.0)

set_exhaustiveness(value)#

Set the docking exhaustiveness.

Parameters:: value (Optional[int]) – Exhaustiveness value, or None to leave backend default behavior.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_num_modes(value)#

Set the maximum number of output poses.

Parameters:: value (Optional[int]) – Number of docking modes / poses to request.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_cpu(value)#

Set the number of CPU threads used by the backend.

Parameters:: value (Optional[int]) – CPU count, or None to defer to backend default behavior.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_seed(value)#

Set the random seed for the docking backend.

Parameters:: value (Optional[int]) – Random seed, or None to defer to backend default behavior.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_out(out_path)#

Set the output pose file path.

Parameters:: out_path (PathLike) – Output docking pose file path.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_log(log_path)#

Set the backend log file path.

Parameters:: log_path (PathLike) – Log file path.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

set_executable(exe_path)#

Override the backend executable path or executable name.

If the backend exposes set_executable(), it is used directly. Otherwise the executable name is assigned to exe_name.

Parameters:: exe_path (PathLike) – Path to the backend executable.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

apply_engine_options(options)#

Apply arbitrary engine-specific options.

Resolution order for each option key is:

call a facade setter named set_<key>, if present,
call a backend setter named set_<key>, if present,
otherwise set the attribute directly on the backend.

Parameters:: options (Dict[str, Any]) – Mapping of engine option names to values.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

Example#

dock.apply_engine_options(
    {
        "cpu": 4,
        "seed": 42,
        "exhaustiveness": 8,
    }
)

apply_config(config)#

Apply a configuration onto the current instance.

This method mutates the existing instance using configuration values.

Parameters:: config (Union[str, Path, Dict[str, Any], SingleConfig]) – Configuration represented as a config object, mapping, or file path.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

Example#

dock = SingleDock("qvina").apply_config("config.json")

load_config(config)#

Alias for apply_config() to support fluent configuration loading.

Parameters:: config (Union[str, Path, Dict[str, Any], SingleConfig]) – Configuration represented as a config object, mapping, or file path.
Returns:: The current instance for fluent chaining.
Return type:: SingleDock

Example#

dock = SingleDock("qvina").load_config("config.json")

run(*, exhaustiveness=None, n_poses=None)#

Execute the docking backend and collect run artifacts.

Parameters:

exhaustiveness (Optional[int]) – Optional run-time override for exhaustiveness.
n_poses (Optional[int]) – Optional run-time override for number of poses.

Returns:

Result object containing run artifacts and backend metadata.

Return type:

SingleResult

Example#

result = dock.run(exhaustiveness=8, n_poses=10)

classmethod from_config(config)#

Build a new SingleDock instance from configuration.

Unlike apply_config(), this method creates a fresh facade instance using the engine declared by the configuration.

Parameters:: config (Union[str, Path, Dict[str, Any], SingleConfig]) – Configuration represented as a config object, mapping, or file path.
Returns:: Newly configured docking facade.
Return type:: SingleDock

Example#

dock = SingleDock.from_config("config.json")

classmethod run_from_config(config)#

Construct and execute a docking run directly from configuration.

Parameters:: config (Union[str, Path, Dict[str, Any], SingleConfig]) – Configuration represented as a config object, mapping, or file path.
Returns:: Result object for the executed run.
Return type:: SingleResult

Example#

result = SingleDock.run_from_config("config.json")

run_with_config(config, *, prefer='config')#

Execute a run using a provided configuration and a precedence strategy.

When prefer="config", a fresh instance is created from the supplied configuration and the current object is not reused. When prefer="instance", the configuration is applied onto the existing object before running.

Parameters:

config (Union[str, Path, Dict[str, Any], SingleConfig]) – Configuration represented as a config object, mapping, or file path.
prefer (str) – Precedence mode. Must be either "config" or "instance".

Returns:

Result object for the executed run.

Return type:

SingleResult

Raises:

ValueError – If prefer is not one of "config" or "instance".

Example#

result = dock.run_with_config("config.json", prefer="instance")

Batch docking #

class DockTask( job_id, receptor_id, engine_name, ligand_id, receptor, ligand, center=None, size=None, autobox_ref=None, autobox_pad=None, exhaustiveness=None, n_poses=None, cpu=None, seed=None, executable=None, engine_options=<factory>, out_path=None, log_path=None, retries=1, timeout=None, )#

Bases: object

Concrete docking task consumed by the batch worker.

A DockTask is the normalized unit of work produced by BatchDock. It contains fully resolved receptor, ligand, engine, path, and runtime parameters ready to be executed by worker_process_job_using_singledock().

Parameters:

job_id (str) – Unique job identifier, typically composed from receptor id, engine name, and ligand id.
receptor_id (str) – Logical receptor identifier for grouping and reporting.
engine_name (str) – Docking engine key, for example "vina" or "qvina".
ligand_id (str) – Logical ligand identifier for grouping and reporting.
receptor (str) – Receptor input file path.
ligand (str) – Ligand input file path.
center (Optional[Vec3]) – Optional docking box center.
size (Optional[Vec3]) – Optional docking box size.
autobox_ref (Optional[str]) – Optional reference structure used for autoboxing when an explicit box is not provided.
autobox_pad (Optional[float]) – Optional padding added around the autobox reference.
exhaustiveness (Optional[int]) – Optional docking exhaustiveness value.
n_poses (Optional[int]) – Optional number of output poses to request.
cpu (Optional[int]) – Optional CPU count.
seed (Optional[int]) – Optional random seed.
executable (Optional[str]) – Optional explicit backend executable path.
engine_options (Dict[str, Any]) – Additional engine-specific options to apply before running.
out_path (Optional[str]) – Output docking pose path.
log_path (Optional[str]) – Log file path.
retries (int) – Number of times the task may be retried upon failure.
timeout (Optional[float]) – Optional timeout placeholder for future orchestration logic.

job_id: str#

receptor_id: str#

engine_name: str#

ligand_id: str#

receptor: str#

ligand: str#

center: Tuple[float, float, float] | None = None#

size: Tuple[float, float, float] | None = None#

autobox_ref: str | None = None#

autobox_pad: float | None = None#

exhaustiveness: int | None = None#

n_poses: int | None = None#

cpu: int | None = None#

seed: int | None = None#

executable: str | None = None#

engine_options: Dict[str, Any]#

out_path: str | None = None#

log_path: str | None = None#

retries: int = 1#

timeout: float | None = None#

class DockResult( job_id, receptor_id, engine_name, ligand_id, success, out_path, log_path, called=None, error=None, traceback=None, elapsed=None, metadata=<factory>, )#

Bases: object

Result record returned for each completed docking task.

Parameters:

job_id (str) – Unique job identifier of the executed task.
receptor_id (str) – Receptor identifier associated with the task.
engine_name (str) – Docking engine key used for the task.
ligand_id (str) – Ligand identifier associated with the task.
success (bool) – Whether the task completed successfully.
out_path (Optional[str]) – Output docking pose path, if defined.
log_path (Optional[str]) – Log file path, if defined.
called (Optional[str]) – Backend-reported command line or invocation summary, if available.
error (Optional[str]) – Human-readable error message on failure.
traceback (Optional[str]) – Python traceback captured on failure.
elapsed (Optional[float]) – Elapsed wall-clock time in seconds.
metadata (Dict[str, Any]) – Additional backend metadata emitted during the run.

job_id: str#

receptor_id: str#

engine_name: str#

ligand_id: str#

success: bool#

out_path: str | None#

log_path: str | None#

called: str | None = None#

error: str | None = None#

traceback: str | None = None#

elapsed: float | None = None#

metadata: Dict[str, Any]#

worker_process_job_using_singledock(task_dict)#

Execute one serialized DockTask using SingleDock.

This function is intentionally top-level so it can be pickled and used by concurrent.futures.ProcessPoolExecutor.

The input and output are plain dictionaries to simplify cross-process transport. Internally, the function reconstructs a DockTask, performs the docking run, and returns a serialized DockResult.

Parameters:: task_dict (Dict[str, Any]) – Serialized docking task dictionary, typically produced by dataclasses.asdict().
Returns:: Serialized docking result dictionary.
Return type:: Dict[str, Any]

Example#

task = DockTask(
    job_id="4WKQ:qvina:erlotinib",
    receptor_id="4WKQ",
    engine_name="qvina",
    ligand_id="erlotinib",
    receptor="4WKQ.pdbqt",
    ligand="erlotinib.pdbqt",
)
result = worker_process_job_using_singledock(asdict(task))

class BatchDock( engine='vina', *, n_jobs=1, progress=True, default_retries=1, timeout=None, tmp_root=None, )#

Bases: object

Parallel docking orchestrator for flat and receptor-centric batch layouts.

The class supports two input styles:

flat row-based batches using DockRow
hierarchical receptor-centric batches using ReceptorSpec

Tasks are normalized into DockTask instances and then executed either serially or in parallel through a process pool.

Parameters:

engine (str) – Default engine name used when a flat row batch does not override it.
n_jobs (int) – Number of worker processes. Values below 1 are coerced to 1.
progress (bool) – Whether a progress bar should be shown when tqdm is available.
default_retries (int) – Default retry count used for tasks without an explicit retry override.
timeout (Optional[float]) – Optional timeout placeholder stored on generated tasks.
tmp_root (Optional[PathLike]) – Optional temporary root directory placeholder for future extensions.

Example#

batch = BatchDock(engine="qvina", n_jobs=4)

results = batch.run(
    [
        {
            "id": "erlotinib",
            "receptor": "4WKQ.pdbqt",
            "ligand": "erlotinib.pdbqt",
            "center": [2.865, 193.257, 21.367],
            "size": [27.091, 27.091, 27.091],
        }
    ],
    out_dir="docked",
    log_dir="logs",
    exhaustiveness=8,
    n_poses=10,
)

create_tasks( rows, *, engine=None, out_dir=None, log_dir=None, exhaustiveness=None, n_poses=None, cpu=None, seed=None, retries=None, engine_options=None, executable=None, )#

Create normalized tasks from a flat row-based batch definition.

Per-row values override method-level defaults when present.

Parameters:

rows (Iterable[Union[DockRow, Dict[str, Any]]]) – Iterable of flat row definitions as DockRow objects or raw dictionaries.
engine (Optional[str]) – Engine name override for the whole batch.
out_dir (Optional[PathLike]) – Global output directory for generated pose files.
log_dir (Optional[PathLike]) – Global log directory.
exhaustiveness (Optional[int]) – Default exhaustiveness value.
n_poses (Optional[int]) – Default number of poses.
cpu (Optional[int]) – Default CPU count.
seed (Optional[int]) – Default random seed.
retries (Optional[int]) – Default retry count.
engine_options (Optional[Dict[str, Any]]) – Default engine-specific options merged with per-row options.
executable (Optional[str]) – Optional executable override applied to every task.

Returns:

List of normalized docking tasks.

Return type:

List[DockTask]

Example#

tasks = BatchDock(engine="qvina").create_tasks(
    [
        {
            "id": "erlotinib",
            "receptor": "4WKQ.pdbqt",
            "ligand": "erlotinib.pdbqt",
            "center": [2.865, 193.257, 21.367],
            "size": [27.091, 27.091, 27.091],
        }
    ],
    out_dir="docked",
    log_dir="logs",
    exhaustiveness=8,
)

create_tasks_from_receptors(receptors, *, out_dir=None, log_dir=None)#

Create normalized tasks from a receptor-centric batch definition.

This method expands the hierarchy:

receptor -> software -> ligand -> DockTask

Parameters:

receptors (Iterable[Union[ReceptorSpec, Dict[str, Any]]]) – Iterable of receptor-centric definitions as ReceptorSpec objects or raw dictionaries.
out_dir (Optional[PathLike]) – Optional global output directory used when receptor/software-local output roots are not defined.
log_dir (Optional[PathLike]) – Optional global log directory used when receptor/software-local log roots are not defined.

Returns:

List of normalized docking tasks.

Return type:

List[DockTask]

Example#

tasks = BatchDock().create_tasks_from_receptors(
    receptors,
    out_dir="docked",
    log_dir="logs",
)

run_tasks(tasks)#

Execute a collection of normalized docking tasks.

When n_jobs == 1, tasks are executed serially in the current process. Otherwise they are distributed through a concurrent.futures.ProcessPoolExecutor.

Parameters:: tasks (Iterable[DockTask]) – Iterable of normalized docking tasks.
Returns:: List of docking results.
Return type:: List[DockResult]

Example#

tasks = batch.create_tasks(rows)
results = batch.run_tasks(tasks)

run(rows, **kwargs)#

Create and run tasks from a flat row-based batch definition.

This is a convenience wrapper around create_tasks() followed by run_tasks().

Parameters:

rows (Iterable[Union[DockRow, Dict[str, Any]]]) – Iterable of flat row definitions.
kwargs (Any) – Additional keyword arguments forwarded to create_tasks().

Returns:

List of docking results.

Return type:

List[DockResult]

run_receptors(receptors, *, out_dir=None, log_dir=None)#

Create and run tasks from a receptor-centric batch definition.

This is a convenience wrapper around create_tasks_from_receptors() followed by run_tasks().

Parameters:

receptors (Iterable[Union[ReceptorSpec, Dict[str, Any]]]) – Iterable of receptor-centric definitions.
out_dir (Optional[PathLike]) – Optional global output directory.
log_dir (Optional[PathLike]) – Optional global log directory.

Returns:

List of docking results.

Return type:

List[DockResult]

classmethod from_config(config)#

Build a BatchDock instance from a batch configuration.

Parameters:: config (Union[str, Dict[str, Any], BatchConfig]) – Batch configuration represented as a BatchConfig, mapping, or configuration file path.
Returns:: Configured batch orchestrator.
Return type:: BatchDock

Example#

batch = BatchDock.from_config("batch.json")

classmethod run_from_config(config)#

Execute a full batch directly from configuration.

The method automatically dispatches to either flat row execution or receptor-centric execution depending on whether cfg.receptors is populated.

Parameters:: config (Union[str, Dict[str, Any], BatchConfig]) – Batch configuration represented as a BatchConfig, mapping, or configuration file path.
Returns:: List of docking results.
Return type:: List[DockResult]

Example#

results = BatchDock.run_from_config("batch.json")

MatrixDock#: alias of BatchDock

Vina backend #

class VinaEngine(sf_name='vina', cpu=0, seed=None, verbosity=1, no_refine=False)#

Bases: DockBackend

AutoDock Vina Python-package backend.

This backend uses from vina import Vina from the pip package rather than a project-local wrapper. Import is deferred until runtime so module import stays lightweight even when the package is not installed.

The engine supports a chainable configuration style. Receptor, ligand, box, output, and docking options may be set manually, or loaded from a JSON file using load_config().

The expected JSON structure is:

{
  "box": {
    "center": [2.865, 193.257, 21.367],
    "size": [27.091, 27.091, 27.091]
  },
  "cpu": 4,
  "seed": 42,
  "exhaustiveness": 16,
  "n_poses": 20
}

Example#

engine = (
    VinaEngine()
    .set_receptor("protein.pdbqt", validate=True)
    .set_ligand("ligand.pdbqt")
    .load_config("config.json")
    .set_out("poses.pdbqt")
    .set_log("dock.log")
    .run()
)

Example#

engine = VinaEngine()
engine.load_config_dict(
    {
        "box": {
            "center": [2.865, 193.257, 21.367],
            "size": [27.091, 27.091, 27.091],
        },
        "cpu": 4,
        "seed": 42,
        "exhaustiveness": 16,
        "n_poses": 20,
    }
)

property metadata: Dict[str, Any]#

Return a shallow copy of the last recorded runtime metadata.

Returns:: Metadata dictionary describing the most recent docking run.
Return type:: Dict[str, Any]

property called: str | None#

Return a textual representation of the last Vina API call chain.

Returns:: String describing the last executed docking call, or None if the engine has not yet been run.
Return type:: Optional[str]

set_receptor(receptor_path, *, validate=False)#

Set the receptor structure file.

Parameters:

receptor_path (PathLike) – Path to the receptor file, typically a .pdbqt file.
validate (bool) – If True, require that the receptor path already exists on disk.

Raises:

FileNotFoundError – If validate is True and the file does not exist.

Returns:

The current engine instance for method chaining.

Return type:

VinaEngine

set_ligand(ligand_path)#

Set the ligand structure file.

Parameters:: ligand_path (PathLike) – Path to the ligand file, typically a .pdbqt file.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_box(center, size)#

Set the docking search box.

Parameters:

center (Vec3) – Docking box center as (x, y, z).
size (Vec3) – Docking box size as (sx, sy, sz).

Returns:

The current engine instance for method chaining.

Return type:

VinaEngine

load_config(config_path)#

Load docking options from a JSON configuration file.

Supported keys are:

box.center
box.size
cpu
seed
exhaustiveness
n_poses

Unknown keys are ignored.

Parameters:

config_path (PathLike) – Path to a JSON file containing docking configuration.

Raises:

FileNotFoundError – If the configuration file does not exist.
ValueError – If the file content is not a JSON object.

Returns:

The current engine instance for method chaining.

Return type:

VinaEngine

Example#

engine = (
    VinaEngine()
    .set_receptor("protein.pdbqt")
    .set_ligand("ligand.pdbqt")
    .load_config("config.json")
)

load_config_dict(config)#

Load docking options from an in-memory mapping.

Supported keys are:

box.center
box.size
cpu
seed
exhaustiveness
n_poses

Unknown keys are ignored.

Parameters:

config (Mapping[str, Any]) – Mapping containing docking configuration values.

Raises:

TypeError – If provided values have invalid types or malformed vector fields.
ValueError – If the box block is incomplete.

Returns:

The current engine instance for method chaining.

Return type:

VinaEngine

Example#

engine = VinaEngine().load_config_dict(
    {
        "box": {
            "center": [2.865, 193.257, 21.367],
            "size": [27.091, 27.091, 27.091],
        },
        "cpu": 4,
        "seed": 42,
        "exhaustiveness": 16,
        "n_poses": 20,
    }
)

enable_autobox(reference_file, padding=None)#

Reject autobox requests for the Python Vina backend.

Parameters:

reference_file (PathLike) – Reference structure path that would otherwise be used for autoboxing.
padding (Optional[float]) – Optional padding distance that would otherwise enlarge the inferred box.

Raises:

RuntimeError – Always raised, because the Python Vina backend requires an explicit box.

Returns:

This method never returns normally.

Return type:

VinaEngine

set_exhaustiveness(value)#

Set the default docking exhaustiveness.

Parameters:: value (Optional[int]) – Exhaustiveness value, or None to leave unset.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_num_modes(value)#

Set the default number of output poses.

Parameters:: value (Optional[int]) – Number of output modes, or None to leave unset.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_cpu(value)#

Set the number of CPU threads.

Parameters:: value (Optional[int]) – CPU thread count. If None, the current value is preserved.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_seed(value)#

Set the docking random seed.

Parameters:: value (Optional[int]) – Random seed, or None to unset the seed.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_out(out_path)#

Set the output PDBQT path for docked poses.

Parameters:: out_path (PathLike) – Output file path for docked poses.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

set_log(log_path)#

Set the log file path.

Parameters:: log_path (PathLike) – Output file path for the docking log.
Returns:: The current engine instance for method chaining.
Return type:: VinaEngine

run(*, exhaustiveness=None, n_poses=None)#

Execute docking with the configured receptor, ligand, and search box.

Runtime arguments override values previously loaded through load_config(), load_config_dict(), set_exhaustiveness(), and set_num_modes().

Parameters:

exhaustiveness (Optional[int]) – Optional per-run exhaustiveness override. If omitted, the stored engine value is used. If still unset, a default of 8 is used.
n_poses (Optional[int]) – Optional per-run pose-count override. If omitted, the stored engine value is used. If still unset, a default of 9 is used.

Raises:

ValueError – If mandatory receptor, ligand, or box inputs are missing.
ImportError – If the Python vina package is not installed.

Returns:

The current engine instance after docking.

Return type:

VinaEngine

Example#

engine = (
    VinaEngine()
    .set_receptor("protein.pdbqt", validate=True)
    .set_ligand("ligand.pdbqt")
    .load_config("config.json")
    .set_out("poses.pdbqt")
    .set_log("dock.log")
    .run()
)

Parameters:

sf_name (str)
cpu (int)
seed (Optional[int])
verbosity (int)
no_refine (bool)

Smina backend #

class SminaEngine#

Bases: BaseBinaryEngine

smina command-line backend.

exe_name: str = 'smina'#

supports_autobox: bool = True#

Gnina backend #

class GninaEngine#

Bases: BaseBinaryEngine

gnina command-line backend.

exe_name: str = 'gnina'#

supports_autobox: bool = True#

QuickVina 2 backend #

class QVinaEngine#

Bases: BaseBinaryEngine

QuickVina 2 command-line backend.

exe_name: str = 'qvina'#

supports_autobox: bool = False#

flag_map: Dict[str, str] = {'center_x': '--center_x', 'center_y': '--center_y', 'center_z': '--center_z', 'cpu': '--cpu', 'exhaustiveness': '--exhaustiveness', 'ligand': '--ligand', 'log': '--log', 'num_modes': '--num_modes', 'out': '--out', 'receptor': '--receptor', 'seed': '--seed', 'size_x': '--size_x', 'size_y': '--size_y', 'size_z': '--size_z'}#

QuickVina-W backend #

class QVinaWEngine#

Bases: BaseBinaryEngine

QuickVina-W command-line backend.

exe_name: str = 'qvina-w'#

supports_autobox: bool = False#

flag_map: Dict[str, str] = {'center_x': '--center_x', 'center_y': '--center_y', 'center_z': '--center_z', 'cpu': '--cpu', 'exhaustiveness': '--exhaustiveness', 'ligand': '--ligand', 'log': '--log', 'num_modes': '--num_modes', 'out': '--out', 'receptor': '--receptor', 'seed': '--seed', 'size_x': '--size_x', 'size_y': '--size_y', 'size_z': '--size_z'}#