TorsionDrive Dataset¶

TorsionDriveDatasets host the results of TorsionDrive computations. Each row of the TorsionDriveDataset is comprised of an Entry which contains a list of starting molecules for the TorsionDrive, a specific set of dihedral angles (zero-indexed), and the angular scan resolution. Each column represents a particular property detail pertinent to the corresponding TorsionDrive Entry. The TorsionDriveDataset is a procedure-style dataset within which, the ObjectId for each TorsionDrive computation is recorded as metadata.

For additional details about TorsionDriveDatasets see here.

Querying the Data¶

Statistics and Visualization¶

Creating the Datasets¶

A empty instance of the TorsionDriveDataset object (here, named My Torsions) can be constructed as

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

Computational Tasks¶

API¶

class qcfractal.interface.collections.TorsionDriveDataset(name: str, client: FractalClient = None, **kwargs)[source]¶

class DataModel(*, id: str = 'local', name: str, collection: str, provenance: Dict[str, str] = {}, tags: List[str] = [], tagline: str = None, description: str = None, group: str = 'default', visibility: bool = True, view_url_hdf5: str = None, view_url_plaintext: str = None, view_metadata: Dict[str, str] = None, view_available: bool = False, metadata: Dict[str, Any] = {}, records: Dict[str, qcfractal.interface.collections.torsiondrive_dataset.TDEntry] = {}, history: Set[str] = {}, specs: Dict[str, qcfractal.interface.collections.torsiondrive_dataset.TDEntrySpecification] = {})[source]¶

Parameters

id (str, Default: local)
name (str)
collection (str)
provenance (name=’provenance’ type=Mapping[str, str] required=False default={}, Default: {})
tags (List[str], Default: [])
tagline (str, Optional)
description (str, Optional)
group (str, Default: default)
visibility (bool, Default: True)
view_url_hdf5 (str, Optional)
view_url_plaintext (str, Optional)
view_metadata (name=’view_metadata’ type=Optional[Mapping[str, str]] required=False default=None, Optional)
view_available (bool, Default: False)
metadata (Dict[str, Any], Default: {})
records (TDEntry, Default: {})
history (Set[str], Default: set())
specs (TDEntrySpecification, Default: {})

class Config[source]¶

compare(other: Union[qcelemental.models.basemodels.ProtoModel, pydantic.main.BaseModel], **kwargs) → bool¶

Compares the current object to the provided object recursively.

Parameters

other (Model) – The model to compare to.
**kwargs – Additional kwargs to pass to qcelemental.compare_recursive.

Returns

True if the objects match.

Return type

bool

classmethod construct(_fields_set: Optional[SetStr] = None, **values: Any) → Model¶: Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

copy(*, include: Union[AbstractSetIntStr, MappingIntStrAny] = None, exclude: Union[AbstractSetIntStr, MappingIntStrAny] = None, update: DictStrAny = None, deep: bool = False) → Model¶

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters

include – fields to include in new model
exclude – fields to exclude from new model, as with values this takes precedence over include
update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
deep – set to True to make a deep copy of the model

Returns

new model instance

dict(**kwargs) → Dict[str, Any]¶: Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

property fields¶

classmethod from_orm(obj: Any) → Model¶

json(**kwargs)¶

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod parse_file(path: Union[str, pathlib.Path], *, encoding: Optional[str] = None) → qcelemental.models.basemodels.ProtoModel¶

Parses a file into a Model object.

Parameters

path (Union[str, Path]) – The path to the file.
encoding (str, optional) – The type of the files, available types are: {‘json’, ‘msgpack’, ‘pickle’}. Attempts to automatically infer the file type from the file extension if None.

Returns

The requested model from a serialized format.

Return type

Model

classmethod parse_obj(obj: Any) → Model¶

classmethod parse_raw(data: Union[bytes, str], *, encoding: Optional[str] = None) → qcelemental.models.basemodels.ProtoModel¶

Parses raw string or bytes into a Model object.

Parameters

data (Union[bytes, str]) – A serialized data blob to be deserialized into a Model.
encoding (str, optional) – The type of the serialized array, available types are: {‘json’, ‘json-ext’, ‘msgpack-ext’, ‘pickle’}

Returns

The requested model from a serialized format.

Return type

Model

classmethod schema(by_alias: bool = True, ref_template: unicode = '#/definitions/{model}') → DictStrAny¶

classmethod schema_json(*, by_alias: bool = True, ref_template: unicode = '#/definitions/{model}', **dumps_kwargs: Any) → unicode¶

serialize(encoding: str, *, include: Optional[Set[str]] = None, exclude: Optional[Set[str]] = None, exclude_unset: Optional[bool] = None, exclude_defaults: Optional[bool] = None, exclude_none: Optional[bool] = None) → Union[bytes, str]¶

Generates a serialized representation of the model

Parameters

encoding (str) – The serialization type, available types are: {‘json’, ‘json-ext’, ‘msgpack-ext’}
include (Optional[Set[str]], optional) – Fields to be included in the serialization.
exclude (Optional[Set[str]], optional) – Fields to be excluded in the serialization.
exclude_unset (Optional[bool], optional) – If True, skips fields that have default values provided.
exclude_defaults (Optional[bool], optional) – If True, skips fields that have set or defaulted values equal to the default.
exclude_none (Optional[bool], optional) – If True, skips fields that have value None.

Returns

The serialized model.

Return type

Union[bytes, str]

to_string(pretty: bool = False) → unicode¶

classmethod update_forward_refs(**localns: Any) → None¶: Try to update ForwardRefs on fields based on this Model, globalns and localns.

classmethod validate(value: Any) → Model¶

add_entry(name: str, initial_molecules: List[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]¶

Parameters

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: Optional[str] = None, overwrite: bool = False) → None[source]¶

Parameters

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

compute(specification: str, subset: Optional[Set[str]] = None, tag: Optional[str] = None, priority: Optional[str] = None) → int¶

Computes a specification for all entries in the dataset.

Parameters

specification (str) – The specification name.
subset (Set[str], optional) – Computes only a subset of the dataset.
tag (Optional[str], optional) – The queue tag to use when submitting compute requests.
priority (Optional[str], optional) – The priority of the jobs low, medium, or high.

Returns

The number of submitted computations

Return type

int

counts(entries: Union[str, List[str]], specs: Optional[Union[List[str], str]] = None, count_gradients: bool = False) → pandas.core.frame.DataFrame[source]¶

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

Parameters

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.

Returns

The queried counts.

Return type

DataFrame

classmethod from_json(data: Dict[str, Any], client: FractalClient = None) → Collection¶

Creates a new class from a JSON blob

Parameters

data (Dict[str, Any]) – The JSON blob to create a new class from.
client (FractalClient, optional) – A FractalClient connected to a server

Returns

A constructed collection.

Return type

Collection

classmethod from_server(client: FractalClient, name: str) → Collection¶

Creates a new class from a server

Parameters

client (FractalClient) – A FractalClient connected to a server
name (str) – The name of the collection to pull from.

Returns

A constructed collection.

Return type

Collection

get_entry(name: str) → Any¶

Obtains a record from the Dataset

Parameters: name (str) – The record name to pull from.
Returns: The requested record
Return type: Record

get_record(name: str, specification: str) → Any¶

Pulls an individual computational record of the requested name and column.

Parameters

name (str) – The index name to pull the record of.
specification (str) – The name of specification to pull the record of.

Returns

The requested Record

Return type

Any

get_specification(name: str) → Any¶

Parameters: name (str) – The name of the specification
Returns: The requested specification.
Return type: Specification

list_specifications(description=True) → Union[List[str], pandas.core.frame.DataFrame]¶

Lists all available specifications

Parameters: description (bool, optional) – If True returns a DataFrame with Description
Returns: A list of known specification names.
Return type: Union[List[str], ‘DataFrame’]

query(specification: str, force: bool = False) → pandas.core.series.Series¶

Queries a given specification from the server

Parameters

specification (str) – The specification name to query
force (bool, optional) – Force a fresh query if the specification already exists.

Returns

Records collected from the server

Return type

pd.Series

save(client: Optional[FractalClient] = None) → ObjectId¶

Uploads the overall structure of the Collection (indices, options, new molecules, etc) to the server.

Parameters: client (FractalClient, optional) – A FractalClient connected to a server to upload to
Returns: The ObjectId of the saved collection.
Return type: ObjectId

status(specs: Optional[Union[List[str], str]] = None, collapse: bool = True, status: Optional[str] = None, detail: bool = False) → pandas.core.frame.DataFrame¶

Returns the status of all current specifications.

Parameters

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.

Returns

A DataFrame of all known statuses

Return type

DataFrame

to_json(filename: Optional[str] = None)¶

If a filename is provided, dumps the file to disk. Otherwise returns a copy of the current data.

Parameters: filename (str, Optional, Default: None) – The filename to drop the data to.
Returns: ret – A JSON representation of the Collection
Return type: dict

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]¶

Parameters

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.

Returns

The requested figure.

Return type

plotly.Figure