Skip to content

deeporigin.drug_discovery.structures.prepared_system

PreparedSystem holds the output of system preparation: the binding and solvation XML files and the system PDB. You get one back from SystemPrep.run() and pass it to ABFE or RBFE to reuse a prepared system and skip the preparation step.

PreparedSystem -- result of system preparation (ABFE/RBFE) from the platform.

Classes

PreparedSystem dataclass

A prepared protein-ligand system (binding/solvation XML and system PDB paths).

Returned by :meth:SystemPrep.run() <deeporigin.drug_discovery.system_prep.SystemPrep.run> or :meth:PreparedSystem.from_result / :meth:PreparedSystem.from_json. Used as input to ABFE or RBFE workflows.

Attributes:

Name Type Description
id Optional[str]

Result-explorer record ID, if loaded from the platform.
binding_xml_path str

Remote path to the binding XML file.
solvation_xml_path str

Remote path to the solvation XML file.
system_pdb_path str

Remote path to the system PDB file.
solute_pdb_path Optional[str]

Remote path to the solute-only PDB file, if present.
protein_id Optional[str]

Protein ID used for preparation.
ligand1_id Optional[str]

First ligand ID (ABFE or RBFE).
ligand2_id Optional[str]

Second ligand ID (RBFE only); None for ABFE.
padding Optional[float]

Padding distance in nm, if known.
add_H_atoms Optional[bool]

Whether hydrogens were added, if known.
retain_waters Optional[bool]

Whether waters were retained, if known.
protonate_protein Optional[bool]

Whether protein was protonated, if known.
compute_job_id Optional[str]

Compute job ID that produced this result, if known.

Attributes

add_H_atoms class-attribute instance-attribute 
add_H_atoms: Optional[bool] = None
binding_xml_path instance-attribute 
binding_xml_path: str
compute_job_id class-attribute instance-attribute 
compute_job_id: Optional[str] = None
id class-attribute instance-attribute 
id: Optional[str] = None
ligand1_id class-attribute instance-attribute 
ligand1_id: Optional[str] = None
ligand2_id class-attribute instance-attribute 
ligand2_id: Optional[str] = None
padding class-attribute instance-attribute 
padding: Optional[float] = None
protein_id class-attribute instance-attribute 
protein_id: Optional[str] = None
protonate_protein class-attribute instance-attribute 
protonate_protein: Optional[bool] = None
retain_waters class-attribute instance-attribute 
retain_waters: Optional[bool] = None
solute_pdb_path class-attribute instance-attribute 
solute_pdb_path: Optional[str] = None
solvation_xml_path instance-attribute 
solvation_xml_path: str
system_pdb_path instance-attribute 
system_pdb_path: str

Methods:

from_json classmethod 
from_json(data: dict[str, Any]) -> Self

Build a PreparedSystem from API-shaped JSON.

Use the same keys as result-explorer data, sync jobOutputs.system, or a merged payload from :meth:_from_record (paths plus optional metadata).

Required keys: binding_xml_file_path, solvation_xml_ligand_file_path, system_pdb_file_path. Optional keys include solute_pdb_file_path, protein_id, ligand1_id, ligand2_id, padding, add_H_atoms, retain_waters, protonate_protein, id (result row id), and compute_job_id.

Parameters:

Name Type Description Default
data dict[str, Any]

Dict of paths and metadata.

 required

Returns:

Type Description
Self

A populated PreparedSystem.

Raises:

Type Description
ValueError

If required path keys are missing or empty.
from_result classmethod 
from_result(
    *,
    protein_id: str | None = None,
    ligand1_id: str | None = None,
    ligand2_id: str | None = None,
    compute_job_id: str | None = None,
    padding: int | float | None = None,
    add_H_atoms: bool | None = None,
    retain_waters: bool | None = None,
    protonate_protein: bool | None = None,
    client: Optional[DeepOriginClient] = None
) -> list[Self]

Create PreparedSystem objects from system-prep results in the data platform.

Fetches prepared-system results via the result-explorer API and builds a list of PreparedSystem instances.

Parameters:

Name Type Description Default
protein_id str | None

Optional protein ID to filter by.

 None
ligand1_id str | None

Optional first ligand ID to filter by.

 None
ligand2_id str | None

Optional second ligand ID to filter by (RBFE).

 None
compute_job_id str | None

Optional compute job ID to filter by.

 None
padding int | float | None

Optional padding value to filter by.

 None
add_H_atoms bool | None

Optional add_H_atoms flag to filter by.

 None
retain_waters bool | None

Optional retain_waters flag to filter by.

 None
protonate_protein bool | None

Optional protonate_protein flag to filter by.

 None
client Optional[DeepOriginClient]

Optional DeepOriginClient. If not provided, uses the default.

 None

Returns:

Type Description
list[Self]

List of PreparedSystem objects with paths and metadata from the results.

Raises:

Type Description
ValueError

If no prepared-system results are found for the given filters.
show 
show(*, solute: bool = False) -> Any

Visualize the prepared system structure in a Jupyter notebook using MolStar.

By default, downloads the full system PDB from the platform. Pass solute=True to visualize the solute-only structure instead (requires :attr:solute_pdb_path to be set).

Renders with the same protein-only viewer as :meth:Protein.show when called without optional pocket or ligand arguments.

Parameters:

Name Type Description Default
solute bool

If true, use :attr:solute_pdb_path; otherwise :attr:system_pdb_path.

 False

Returns:

Type Description
Any

Output from :func:deeporigin.utils.notebook.render_html (Jupyter
Any

display or marimo HTML wrapper, depending on environment).

Raises:

Type Description
DeepOriginException

If the chosen PDB path is missing or empty, or solute=True but :attr:solute_pdb_path is not available.