TorsionDrive Dataset

TorsionDriveDatasets are sets of TorsionDrive computations where the primary index a set of starting molecules and each column is represented by a new TorsionDrive specification. This Dataset is a procedure-style dataset where a record of the ObjectId of each TorsionDrive computation are recorded in the metadata.




A empty TorsionDriveDataset can be constructed by choosing a dataset name.

client = ptl.FractalClient("localhost:7777")
ds = ptl.collections.TorsionDriveDataset("My Torsions")



class qcfractal.interface.collections.TorsionDriveDataset(name: str, client: FractalClient = None, **kwargs)[source]
class DataModel[source]
add_entry(name: str, initial_molecules: List[qcelemental.models.molecule.Molecule], dihedrals: List[Tuple[int, int, int, int]], grid_spacing: List[int], dihedral_ranges: Optional[List[Tuple[int, int]]] = None, energy_decrease_thresh: Optional[float] = None, energy_upper_limit: Optional[float] = None, attributes: Dict[str, Any] = None, save: bool = True) → None[source]
  • name (str) – The name of the entry, will be used for the index

  • initial_molecules (List[Molecule]) – The list of starting Molecules for the TorsionDrive

  • dihedrals (List[Tuple[int, int, int, int]]) – A list of dihedrals to scan over

  • grid_spacing (List[int]) – The grid spacing for each dihedrals

  • dihedral_ranges (Optional[List[Tuple[int, int]]]) – The range limit of each dihedrals to scan, within [-180, 360]

  • energy_decrease_thresh (Optional[float]) – The threshold of energy decrease to trigger activating grid points

  • energy_upper_limit (Optional[float]) – The upper limit of energy relative to current global minimum to trigger activating grid points

  • attributes (Dict[str, Any], optional) – Additional attributes and descriptions for the entry

  • save (bool, optional) – If true, saves the collection after adding the entry. If this is False be careful to call save after all entries are added, otherwise data pointers may be lost.

add_specification(name: str, optimization_spec: qcfractal.interface.models.common_models.OptimizationSpecification, qc_spec: qcfractal.interface.models.common_models.QCSpecification, description: str = None, overwrite=False) → None[source]
  • name (str) – The name of the specification

  • optimization_spec (OptimizationSpecification) – A full optimization specification for TorsionDrive

  • qc_spec (QCSpecification) – A full quantum chemistry specification for TorsionDrive

  • description (str, optional) – A short text description of the specification

  • overwrite (bool, optional) – Overwrite existing specification names

counts(entries: Union[str, List[str]], specs: Union[List[str], str, None] = None, count_gradients=False) → DataFrame[source]

Counts the number of optimization or gradient evaluations associated with the TorsionDrives.

  • entries (Union[str, List[str]]) – The entries to query for

  • specs (Optional[Union[str, List[str]]], optional) – The specifications to query for

  • count_gradients (bool, optional) – If True, counts the total number of gradient calls. Warning! This can be slow for large datasets.


The queried counts.

Return type


status(specs: Union[str, List[str]] = None, collapse: bool = True, status: Optional[str] = None, detail: bool = False) → DataFrame[source]

Returns the status of all current specifications.

  • specs (Union[str, List[str]], optional) – Description

  • collapse (bool, optional) – Collapse the status into summaries per specification or not.

  • status (Optional[str], optional) – If not None, only returns results that match the provided status.

  • detail (bool, optional) – Shows a detailed description of the current status of incomplete jobs.


A DataFrame of all known statuses

Return type


visualize(entries: Union[str, List[str]], specs: Union[str, List[str]], relative: bool = True, units: str = 'kcal / mol', digits: int = 3, use_measured_angle: bool = False, return_figure: Optional[bool] = None) → plotly.Figure[source]
  • entries (Union[str, List[str]]) – A single or list of indices to plot.

  • specs (Union[str, List[str]]) – A single or list of specifications to plot.

  • relative (bool, optional) – Shows relative energy, lowest energy per scan is zero.

  • units (str, optional) – The units of the plot.

  • digits (int, optional) – Rounds the energies to n decimal places for display.

  • use_measured_angle (bool, optional) – If True, the measured final angle instead of the constrained optimization angle. Can provide more accurate results if the optimization was ill-behaved, but pulls additional data from the server and may take longer.

  • return_figure (Optional[bool], optional) – If True, return the raw plotly figure. If False, returns a hosted iPlot. If None, return a iPlot display in Jupyter notebook and a raw plotly figure in all other circumstances.


The requested figure.

Return type