API¶

Generics¶

`__init__`([address, username, password, verify])	Initializes a FractalClient instance from an address and verification information.
`from_file`([load_path])	Creates a new FractalClient from file.
`server_information`()	Pull down various data on the connected server.

Add/Query Objects¶

`query_kvstore`(id[, full_return])	Queries items from the database’s KVStore
`query_molecules`([id, molecule_hash, …])	Queries molecules from the database.
`add_molecules`(mol_list[, full_return])	Adds molecules to the Server.
`query_keywords`([id, hash_index, limit, …])	Obtains KeywordSets from the server using keyword ids.
`add_keywords`(keywords[, full_return])	Adds KeywordSets to the server.
`list_collections`([collection_type, aslist, …])	Lists the available collections currently on the server.
`get_collection`(collection_type, name[, …])	Acquires a given collection from the server.
`add_collection`(collection[, overwrite, …])	Adds a new Collection to the server.

Records Querying¶

`query_results`([id, task_id, program, …])	Queries ResultRecords from the server.
`query_procedures`([id, task_id, procedure, …])	Queries Procedures from the server.

New Compute Tasks¶

`add_compute`([program, method, basis, …])	Adds a “single” compute to the server.
`add_procedure`(procedure, program, …[, …])	Adds a “single” Procedure to the server.
`add_service`(service[, tag, priority, …])	Adds a new service to the service queue.
`query_tasks`([id, hash_index, program, …])	Checks the status of Tasks in the Fractal queue.
`query_services`([id, procedure_id, …])	Checks the status of services in the Fractal queue.

Function Definitions¶

qcportal.FractalClient.from_file(load_path: Optional[str] = None) → qcfractal.interface.client.FractalClient¶

Creates a new FractalClient from file. If no path is passed in, the current working directory and ~.qca/ are searched for “qcportal_config.yaml”

Parameters: load_path (Optional[str], optional) – Path to find “qcportal_config.yaml”, the filename, or a dictionary containing keys {“address”, “username”, “password”, “verify”}
Returns: A new FractalClient from file.
Return type: FractalClient

qcportal.FractalClient.server_information(self) → Dict[str, str]¶

Pull down various data on the connected server.

Returns: Server information.
Return type: Dict[str, str]

qcportal.FractalClient.query_kvstore(self, id: QueryObjectId, full_return: bool = False) → Dict[str, Any]¶

Queries items from the database’s KVStore

Parameters

id (QueryObjectId) – A list of KVStore id’s
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of found KVStore objects in {“id”: “value”} format

Return type

Dict[str, Any]

qcportal.FractalClient.query_molecules(self, id: Optional[QueryObjectId] = None, molecule_hash: Optional[QueryStr] = None, molecular_formula: Optional[QueryStr] = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → Union[MoleculeGETResponse, List[Molecule]]¶

Queries molecules from the database.

Parameters

id (QueryObjectId, optional) – Queries the Molecule id field.
molecule_hash (QueryStr, optional) – Queries the Molecule molecule_hash field.
molecular_formula (QueryStr, optional) – Queries the Molecule molecular_formula field. Molecular formulas are case-sensitive. Molecular formulas are not order-sensitive (e.g. “H2O == OH2 != Oh2”).
limit (Optional[int], optional) – The maximum number of Molecules to query
skip (int, optional) – The number of Molecules to skip in the query, used during pagination
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of found molecules.

Return type

List[Molecule]

qcportal.FractalClient.add_molecules(self, mol_list: List[Molecule], full_return: bool = False) → List[str]¶

Adds molecules to the Server.

Parameters

mol_list (List[Molecule]) – A list of Molecules to add to the server.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of Molecule id’s in the sent order, can be None where issues occured.

Return type

List[str]

qcportal.FractalClient.query_keywords(self, id: Optional[QueryObjectId] = None, *, hash_index: Optional[QueryStr] = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → Union[KeywordGETResponse, List[KeywordSet]]¶

Obtains KeywordSets from the server using keyword ids.

Parameters

id (QueryObjectId, optional) – A list of ids to query.
hash_index (QueryStr, optional) – The hash index to look up
limit (Optional[int], optional) – The maximum number of keywords to query
skip (int, optional) – The number of keywords to skip in the query, used during pagination
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

The requested KeywordSet objects.

Return type

List[KeywordSet]

qcportal.FractalClient.add_keywords(self, keywords: List[KeywordSet], full_return: bool = False) → List[str]¶

Adds KeywordSets to the server.

Parameters

keywords (List[KeywordSet]) – A list of KeywordSets to add.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A list of KeywordSet id’s in the sent order, can be None where issues occured.

Return type

List[str]

qcportal.FractalClient.list_collections(self, collection_type: Optional[str] = None, aslist: bool = False, group: Optional[str] = 'default', show_hidden: bool = False, tag: Optional[Union[List[str], str]] = None) → pandas.core.frame.DataFrame¶

Lists the available collections currently on the server.

Parameters

collection_type (Optional[str], optional) – If None all collection types will be returned, otherwise only the specified collection type will be returned
aslist (bool, optional) – Returns a canonical list rather than a dataframe.
group (Optional[str], optional) – Show only collections belonging to a specified group. To explicitly return all collections, set group=None
show_hidden (bool, optional) – Show collections whose visibility flag is set to False. Default: False.
tag (Optional[Union[str, List[str]]], optional) – Show collections whose tags match one of the passed tags. By default, collections are not filtered on tag.

Returns

A dataframe containing the collection, name, and tagline.

Return type

DataFrame

qcportal.FractalClient.get_collection(self, collection_type: str, name: str, full_return: bool = False, include: QueryListStr = None, exclude: QueryListStr = None) → Collection¶

Acquires a given collection from the server.

Parameters

collection_type (str) – The collection type to be accessed
name (str) – The name of the collection to be accessed
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.
include (QueryListStr, optional) – Return only these columns.
exclude (QueryListStr, optional) – Return all but these columns.

Returns

A Collection object if the given collection was found otherwise returns None.

Return type

Collection

qcportal.FractalClient.add_collection(self, collection: Dict[str, Any], overwrite: bool = False, full_return: bool = False) → Union[CollectionGETResponse, List[ObjectId]]¶

Adds a new Collection to the server.

Parameters

collection (Dict[str, Any]) – The full collection data representation.
overwrite (bool, optional) – Overwrites the collection if it already exists in the database, used for updating collection.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

The ObjectId’s of the added collection.

Return type

List[ObjectId]

qcportal.FractalClient.query_results(self, id: Optional[QueryObjectId] = None, task_id: Optional[QueryObjectId] = None, program: Optional[QueryStr] = None, molecule: Optional[QueryObjectId] = None, driver: Optional[QueryStr] = None, method: Optional[QueryStr] = None, basis: Optional[QueryStr] = None, keywords: Optional[QueryObjectId] = None, status: QueryStr = 'COMPLETE', limit: Optional[int] = None, skip: int = 0, include: Optional[QueryListStr] = None, full_return: bool = False) → Union[ResultGETResponse, List[ResultRecord], Dict[str, Any]]¶

Queries ResultRecords from the server.

Parameters

id (QueryObjectId, optional) – Queries the Result id field.
task_id (QueryObjectId, optional) – Queries the Result task_id field.
program (QueryStr, optional) – Queries the Result program field.
molecule (QueryObjectId, optional) – Queries the Result molecule field.
driver (QueryStr, optional) – Queries the Result driver field.
method (QueryStr, optional) – Queries the Result method field.
basis (QueryStr, optional) – Queries the Result basis field.
keywords (QueryObjectId, optional) – Queries the Result keywords field.
status (QueryStr, optional) – Queries the Result status field.
limit (Optional[int], optional) – The maximum number of Results to query
skip (int, optional) – The number of Results to skip in the query, used during pagination
include (QueryListStr, optional) – Filters the returned fields, will return a dictionary rather than an object.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

Returns a List of found RecordResult’s without include, or a dictionary of results with include.

Return type

Union[List[RecordResult], Dict[str, Any]]

qcportal.FractalClient.query_procedures(self, id: Optional[QueryObjectId] = None, task_id: Optional[QueryObjectId] = None, procedure: Optional[QueryStr] = None, program: Optional[QueryStr] = None, hash_index: Optional[QueryStr] = None, status: QueryStr = 'COMPLETE', limit: Optional[int] = None, skip: int = 0, include: Optional[QueryListStr] = None, full_return: bool = False) → Union[ProcedureGETResponse, List[Dict[str, Any]]]¶

Queries Procedures from the server.

Parameters

id (QueryObjectId, optional) – Queries the Procedure id field.
task_id (QueryObjectId, optional) – Queries the Procedure task_id field.
procedure (QueryStr, optional) – Queries the Procedure procedure field.
program (QueryStr, optional) – Queries the Procedure program field.
hash_index (QueryStr, optional) – Queries the Procedure hash_index field.
status (QueryStr, optional) – Queries the Procedure status field.
limit (Optional[int], optional) – The maximum number of Procedures to query
skip (int, optional) – The number of Procedures to skip in the query, used during pagination
include (QueryListStr, optional) – Filters the returned fields, will return a dictionary rather than an object.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

Returns a List of found RecordResult’s without include, or a dictionary of results with include.

Return type

Union[List[‘RecordBase’], Dict[str, Any]]

qcportal.FractalClient.add_compute(self, program: str = None, method: str = None, basis: Optional[str] = None, driver: str = None, keywords: Optional[ObjectId] = None, molecule: Union[ObjectId, Molecule, List[Union[ObjectId, Molecule]]] = None, *, priority: Optional[str] = None, protocols: Optional[Dict[str, Any]] = None, tag: Optional[str] = None, full_return: bool = False) → ComputeResponse¶

Adds a “single” compute to the server.

Parameters

program (str, optional) – The computational program to execute the result with (e.g., “rdkit”, “psi4”).
method (str, optional) – The computational method to use (e.g., “B3LYP”, “PBE”)
basis (Optional[str], optional) – The basis to apply to the computation (e.g., “cc-pVDZ”, “6-31G”)
driver (str, optional) – The primary result that the compute will aquire {“energy”, “gradient”, “hessian”, “properties”}
keywords (Optional[‘ObjectId’], optional) – The KeywordSet ObjectId to use with the given compute
molecule (Union[‘ObjectId’, ‘Molecule’, List[Union[‘ObjectId’, ‘Molecule’]]], optional) – The Molecules or Molecule ObjectId’s to compute with the above methods
priority (Optional[str], optional) – The priority of the job {“HIGH”, “MEDIUM”, “LOW”}. Default is “MEDIUM”.
protocols (Optional[Dict[str, Any]], optional) – Protocols for store more or less data per field. Current valid protocols: {‘wavefunction’}
tag (Optional[str], optional) – The computational tag to add to your compute, managers can optionally only pull based off the string tags. These tags are arbitrary, but several examples are to use “large”, “medium”, “small” to denote the size of the job or “project1”, “project2” to denote different projects.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new compute. This object has the following fields:

ids: The ObjectId’s of the task in the order of input molecules
submitted: A list of ObjectId’s that were submitted to the compute queue
existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

Raises

ValueError – Description

qcportal.FractalClient.add_procedure(self, procedure: str, program: str, program_options: Dict[str, Any], molecule: Union[ObjectId, Molecule, List[Union[str, Molecule]]], priority: Optional[str] = None, tag: Optional[str] = None, full_return: bool = False) → ComputeResponse¶

Adds a “single” Procedure to the server.

Parameters

procedure (str) – The computational procedure to spawn {“optimization”}
program (str) – The program to use for the given procedure (e.g., “geomeTRIC”)
program_options (Dict[str, Any]) – Additional options and specifications for the given procedure.
molecule (Union[ObjectId, Molecule, List[Union[str, Molecule]]]) – The Molecules or Molecule ObjectId’s to use with the above procedure
priority (str, optional) – The priority of the job {“HIGH”, “MEDIUM”, “LOW”}. Default is “MEDIUM”.
tag (str, optional) – The computational tag to add to your procedure, managers can optionally only pull based off the string tags. These tags are arbitrary, but several examples are to use “large”, “medium”, “small” to denote the size of the job or “project1”, “project2” to denote different projects.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new procedure. This object has the following fields:

ids: The ObjectId’s of the task in the order of input molecules
submitted: A list of ObjectId’s that were submitted to the compute queue
existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

qcportal.FractalClient.query_tasks(self, id: Optional[QueryObjectId] = None, hash_index: Optional[QueryStr] = None, program: Optional[QueryStr] = None, status: Optional[QueryStr] = None, base_result: Optional[QueryStr] = None, tag: Optional[QueryStr] = None, manager: Optional[QueryStr] = None, limit: Optional[int] = None, skip: int = 0, include: Optional[QueryListStr] = None, full_return: bool = False) → Union[TaskQueueGETResponse, List[TaskRecord], List[Dict[str, Any]]]¶

Checks the status of Tasks in the Fractal queue.

Parameters

id (QueryObjectId, optional) – Queries the Tasks id field.
hash_index (QueryStr, optional) – Queries the Tasks hash_index field.
program (QueryStr, optional) – Queries the Tasks program field.
status (QueryStr, optional) – Queries the Tasks status field.
base_result (QueryStr, optional) – Queries the Tasks base_result field.
tag (QueryStr, optional) – Queries the Tasks tag field.
manager (QueryStr, optional) – Queries the Tasks manager field.
limit (Optional[int], optional) – The maximum number of Tasks to query
skip (int, optional) – The number of Tasks to skip in the query, used during pagination
include (QueryListStr, optional) – Filters the returned fields, will return a dictionary rather than an object.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A dictionary of each match that contains the current status and, if an error has occurred, the error message.

Return type

List[Dict[str, Any]]

Examples

>>> client.query_tasks(id="5bd35af47b878715165f8225",include=["status"])
[{"status": "WAITING"}]

qcportal.FractalClient.add_service(self, service: Union[List[GridOptimizationInput], List[TorsionDriveInput]], tag: Optional[str] = None, priority: Optional[str] = None, full_return: bool = False) → ComputeResponse¶

Adds a new service to the service queue.

Parameters

service (Union[GridOptimizationInput, TorsionDriveInput]) – An available service input
tag (Optional[str], optional) – The compute tag to add the service under.
priority (Optional[str], optional) – The priority of the job within the compute queue.
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

An object that contains the submitted ObjectIds of the new service. This object has the following fields:

ids: The ObjectId’s of the task in the order of input molecules
submitted: A list of ObjectId’s that were submitted to the compute queue
existing: A list of ObjectId’s of tasks already in the database

Return type

ComputeResponse

qcportal.FractalClient.query_services(self, id: Optional[QueryObjectId] = None, procedure_id: Optional[QueryObjectId] = None, hash_index: Optional[QueryStr] = None, status: Optional[QueryStr] = None, limit: Optional[int] = None, skip: int = 0, full_return: bool = False) → Union[ServiceQueueGETResponse, List[Dict[str, Any]]]¶

Checks the status of services in the Fractal queue.

Parameters

id (QueryObjectId, optional) – Queries the Services id field.
procedure_id (QueryObjectId, optional) – Queries the Services procedure_id field, or the ObjectId of the procedure associated with the service.
hash_index (QueryStr, optional) – Queries the Services procedure_id field.
status (QueryStr, optional) – Queries the Services status field.
limit (Optional[int], optional) – The maximum number of Services to query
skip (int, optional) – The number of Services to skip in the query, used during pagination
full_return (bool, optional) – Returns the full server response if True that contains additional metadata.

Returns

A dictionary of each match that contains the current status and, if an error has occurred, the error message.

Return type

List[Dict[str, Any]]